Gold Medal Software 3

home *** CD-ROM | disk | FTP | other *** search

/ Gold Medal Software 3 / Gold Medal Software - Volume 3 (Gold Medal) (1994).iso / comms / icom0425.arj / SCRIPT.DOC < prev next >

Wrap

Text File | 1994-04-25 | 597KB | 15,163 lines

Intellicomm (TM) v2.01 Copyright (C) 1991-1994 Liberation Enterprises. All rights reserved. --------------------------------------------------------------------- INTELLICOMM SCRIPT LANGUAGE DOCUMENTATION --------------------------------------------------------------------- This document should be used only after you have read the script intro- duction in SCRTUTOR.DOC (included with Intellicomm). If you haven't, please start there first. It is very important that you read the 'introduction' sections in both the SCRIPT COMMANDS AT A GLANCE and DETAILED COMMAND SUMMARIES sections. After you read the introductions, you'll have no trouble understanding this documentation. If you skip the introductions you may have a LOT of trouble. TABLE OF CONTENTS 1. SCRIPT COMMANDS AT A GLANCE . . . . . . . . . . . . . . . . . . . 1 1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 Video (Screen) and Cursor Commands . . . . . . . . . . . . . 1 1.3 Menu Handling . . . . . . . . . . . . . . . . . . . . . . . 3 1.4 Keyboard Input and Output . . . . . . . . . . . . . . . . . 4 1.5 Communications . . . . . . . . . . . . . . . . . . . . . . . 5 1.6 Icom Information / Script Variables . . . . . . . . . . . . 8 1.7 Text (String) Handling . . . . . . . . . . . . . . . . . . . 9 1.8 Math Commands . . . . . . . . . . . . . . . . . . . . . . 10 1.9 DOS and File Input/Output Commands . . . . . . . . . . . . 11 1.10 Date and Time . . . . . . . . . . . . . . . . . . . . . . 13 1.11 Script Flow / Decision-Making . . . . . . . . . . . . . . 13 1.12 Other Useful Commands . . . . . . . . . . . . . . . . . . 14 1.13 File Tagger Commands (Advanced use only) . . . . . . . . 15 2. USING THE DETAILED COMMAND SUMMARIES . . . . . . . . . . . . . 20 2.1 COMMAND Description . . . . . . . . . . . . . . . . . . . 20 2.2 SUMMARY Description . . . . . . . . . . . . . . . . . . . 20 2.2.1 How to Specify Parameters (21) 2.3 ERRORLEVEL Description . . . . . . . . . . . . . . . . . . 22 3. DETAILED COMMAND SUMMARY . . . . . . . . . . . . . . . . . . . 24 ADD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 ADDSLASH . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 ALARM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 AND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 APPEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 APPENDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 APPENDSNC . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 ASSIGN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 BEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 BOX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 BOXGETS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 CADDREC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 CAPCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 CAPPAUSE . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 CAPSTAMP . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 CAPPUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Intellicomm v2.01 SCRIPT.DOC ii CAPPOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 CAPTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 CCLEARBUF . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 CCLEARDESC . . . . . . . . . . . . . . . . . . . . . . . . . . 40 CCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 CDATE2DATE . . . . . . . . . . . . . . . . . . . . . . . . . . 41 CDATEDIFF . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 CDELREC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 CEDITREC . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 CEMPTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 CEXPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 CFLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 CFORMATDESC . . . . . . . . . . . . . . . . . . . . . . . . . . 47 CGETC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 CGETDESC . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 CGETREC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 CGETS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 CHAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 CHECKVERSION . . . . . . . . . . . . . . . . . . . . . . . . . 53 CHDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 CIMPORTNEW . . . . . . . . . . . . . . . . . . . . . . . . . . 54 CIMPORTTEXT . . . . . . . . . . . . . . . . . . . . . . . . . . 55 CLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 CNOTEREC . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 COPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 COPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 CPACK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 CPURGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 CPUTDESC . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 CPUTREC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 CSAVEBMARK . . . . . . . . . . . . . . . . . . . . . . . . . . 63 CSAVEVDATE . . . . . . . . . . . . . . . . . . . . . . . . . . 64 CSEEK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 CSETSORT . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 CTAGALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 CTAGREC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 CTELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 CURSORLARGE . . . . . . . . . . . . . . . . . . . . . . . . . . 69 CURSORSMALL . . . . . . . . . . . . . . . . . . . . . . . . . . 69 CURSOROFF . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 CURSORON . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 CURSORPOP . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 CURSORPUSH . . . . . . . . . . . . . . . . . . . . . . . . . . 70 DATE2CDATE . . . . . . . . . . . . . . . . . . . . . . . . . . 71 DEBUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 DEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 DELAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 DELAYNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 DEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 DIAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 DIREXIST . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 DISKFIND . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 DISKFREE . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 DIV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 DOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 DOWNLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 EDIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Intellicomm v2.01 SCRIPT.DOC iii ERASELINE . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 EXEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 EXIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 FCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 FFLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 FGETC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 FILEMAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 FILESIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 FINDFIRST . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 FINDNEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 FNSTRIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 FOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 FPUTC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 FPUTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 FPUTSNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 FSEEK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 FTELL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 GETENV . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 GETFNAME . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 GETS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 GETSXY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 GOSUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 RETURN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 GOTOXY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 HANGUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 HELPFIND . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 IF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 ELSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 INC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 INITMODEM . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 INKEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 INKEYT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 INKEYW . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 KBFLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 LIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 LOADBIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 LOADINI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 LOCATEFILE . . . . . . . . . . . . . . . . . . . . . . . . . . 117 LOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 LOGCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 MENUBAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 MENUBOXH . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 MENUBOXV . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 MENUDEFINE . . . . . . . . . . . . . . . . . . . . . . . . . . 122 MENUHLP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 MENUITEMSTAT . . . . . . . . . . . . . . . . . . . . . . . . . 123 MKDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 MSGOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 MSGCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 MSGWIND . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Intellicomm v2.01 SCRIPT.DOC iv MUL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 NEWAREA . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 NOTEXIST . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 OFFLINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 ONLINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 OR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 PAUSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 PRINTNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 PRINTRAW . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 PORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 REDIAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 RELOADSCRIPT . . . . . . . . . . . . . . . . . . . . . . . . . 137 RENAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 RENUMBER . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 RETURN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 RMDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 RXFLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 SAVEBIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 SAVEINI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 SCAPTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 SCREENBLANK . . . . . . . . . . . . . . . . . . . . . . . . . . 143 SCREENRESTORE . . . . . . . . . . . . . . . . . . . . . . . . . 143 SCRIPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 SCROLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 SCROLLBACK . . . . . . . . . . . . . . . . . . . . . . . . . . 146 SEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 SENDNC . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 SENDNCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 SENDNP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 SENDBIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 SENDKEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 SENDBREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 SETENV . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 SETCOMM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 SHL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 SHOWWHENS . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 SHR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 STAMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 STRBLANK . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 STRCHR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 STRCHRI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 STRCPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 STRDEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 STRINS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 STRIPSLASH . . . . . . . . . . . . . . . . . . . . . . . . . . 160 STRITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 STRLEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 STRLOWER . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 STRCAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 STRPAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 STRPADL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 STRSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 STRPOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Intellicomm v2.01 SCRIPT.DOC v STRRCHR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 STRRCHRI . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 STRREPLACE . . . . . . . . . . . . . . . . . . . . . . . . . . 168 STRSTRIP . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 STRBTRIM . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 STRLTRIM . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 STRTRIM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 STRUPPER . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 SUB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 SUBSTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 SWITCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 CASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 ENDCASE . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 DEFAULT . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 ENDSWITCH . . . . . . . . . . . . . . . . . . . . . . . . . . 171 SYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 TAGGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 TERMINAL . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 TIMERTOTAL . . . . . . . . . . . . . . . . . . . . . . . . . . 176 TIMEUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 TONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 TXFLUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 UPDATEDNDX . . . . . . . . . . . . . . . . . . . . . . . . . . 179 UPLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 VARIABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 VPUSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 VGETCHR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 VGETCHRS . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 VPOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 WAITFOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 WAITUNTIL . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 WHEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 WHILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 ENDWHILE . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 WINDOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 WNDCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 WNDOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 XOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 A. SYSTEM VARIABLES . . . . . . . . . . . . . . . . . . . . . . . 195 A.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . 195 A.1.1 BIF and INI (main setup) Variables (195); A.1.2 Changing System Variables (195); A.1.3 READ ONLY System Variables (196) A.2 System Variable Summary . . . . . . . . . . . . . . . . . 197 $ALARMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 $BAR_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . 197 $BBS_AREA . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 $BETA_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . 197 $BIF_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 $BIF_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Intellicomm v2.01 SCRIPT.DOC vi $BOLD_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . 198 $BORDER_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . 198 $BSSWAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 $CAP_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 $CAP_STAT . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 $CAREA_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . 198 $CARRIER . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 $CAT_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 $CAT_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 $CCDATE_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . 199 $CDAY_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 $CFDATE_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . 199 $CFLAG_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . 199 $CLOC_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 $CNAME_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . 200 $COM_PORT . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 $CPRIORITY_FLD . . . . . . . . . . . . . . . . . . . . . . . . 200 $COM_SPEED . . . . . . . . . . . . . . . . . . . . . . . . . . 201 $CREC_STAT . . . . . . . . . . . . . . . . . . . . . . . . . . 201 $CSIZE_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . 201 $CSORT_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . 201 $CSORT_ORDER . . . . . . . . . . . . . . . . . . . . . . . . . 201 $CTAG_FLD . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 $CTOTAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 $CVTOTAL . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 $CURDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 $CURDRIVE . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 $DATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 $DAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 $DL_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 $DL_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . . 202 $DOORWAY . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 $DOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 $DSEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 $ECHO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 $ERRORLEVEL . . . . . . . . . . . . . . . . . . . . . . . . . . 203 $FARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 $FDATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 $FDAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 $FHIDDEN . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 $FHOUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 $FMIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 $FMONTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 $FRDONLY . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 $FSEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 $FSIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 $FSUBDIR . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 $FSYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 $FTIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 $FVOLID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 $FULL_SCRIPT_NAME . . . . . . . . . . . . . . . . . . . . . . . 204 $FYEAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 $HOME_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 $HOTKEY_1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Intellicomm v2.01 SCRIPT.DOC vii $HOTKEY_2 . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 $HOTKEY_3 . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 $HOTKEY_4 . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 $HOTKEY_5 . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 $HOUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 $HSEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 $INI_NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 $KEY_ALTQ . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 $KEY_CHECK . . . . . . . . . . . . . . . . . . . . . . . . . . 205 $KEY_FILTER . . . . . . . . . . . . . . . . . . . . . . . . . . 205 $LINEFEED . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 $LST_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 $MAJOR_VERSION . . . . . . . . . . . . . . . . . . . . . . . . 206 $MENUSELECTION . . . . . . . . . . . . . . . . . . . . . . . . 206 $MIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 $MINOR_VERSION . . . . . . . . . . . . . . . . . . . . . . . . 206 $MONTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 $MSG_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 $MSG_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . . 207 $NORM_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . 207 $PASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 $OPSYSTYPE . . . . . . . . . . . . . . . . . . . . . . . . . . 207 $PRN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 $REP_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 $REP_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . . 208 $RXCNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 $SCRIPT_DIR . . . . . . . . . . . . . . . . . . . . . . . . . . 208 $SCRIPT_NAME . . . . . . . . . . . . . . . . . . . . . . . . . 208 $SCRN_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . 208 $SCRN_HEIGHT . . . . . . . . . . . . . . . . . . . . . . . . . 208 $SCRN_WIDTH . . . . . . . . . . . . . . . . . . . . . . . . . . 208 $SCRN_WRAP . . . . . . . . . . . . . . . . . . . . . . . . . . 208 $SCRN_X . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 $SCRN_Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 $SEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 $SEND_CR . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 $SOUND . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 $STAT_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . 209 $STAT_ON . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 $TERM_COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . 210 $TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 $TSEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 $TXCNT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 $UL_PATH . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 $UL_PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . . 211 $VIEW_DATE . . . . . . . . . . . . . . . . . . . . . . . . . . 211 $WND_BTM . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 $WND_HEIGHT . . . . . . . . . . . . . . . . . . . . . . . . . . 211 $WND_LEFT . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 $WND_RIGHT . . . . . . . . . . . . . . . . . . . . . . . . . . 211 $WND_TOP . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 $WND_WIDTH . . . . . . . . . . . . . . . . . . . . . . . . . . 212 $YEAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Intellicomm v2.01 SCRIPT.DOC viii B. BIF VARIABLES (Advanced Users Only) . . . . . . . . . . . . . . 213 C. MAIN SETUP VARIABLES (Advanced Users Only) . . . . . . . . . . 216 D. COLOR CODES . . . . . . . . . . . . . . . . . . . . . . . . . . 224 D.1 Using Color Variables . . . . . . . . . . . . . . . . . . 225 E. ASCII CODES . . . . . . . . . . . . . . . . . . . . . . . . . . 225 E.1 How to Use the ASCII Table . . . . . . . . . . . . . . . . 226 F. KEYBOARD CODES . . . . . . . . . . . . . . . . . . . . . . . . 228 F.1 How to use the Keyboard Codes . . . . . . . . . . . . . . 228 F.2 Example of Usage . . . . . . . . . . . . . . . . . . . . . 229 G. SCRIPT ERROR MESSAGES/SOLUTIONS . . . . . . . . . . . . . . . . 233 H. SCRIPT MEMORY LIMITS . . . . . . . . . . . . . . . . . . . . . 238 H.1 Developing Large Scripts . . . . . . . . . . . . . . . . . 238 I. CREATING SCRIPTS FOR PUBLIC DISTRIBUTION . . . . . . . . . . . 239 J. CHANGES FROM THE V1.00 SCRIPT LANGUAGE . . . . . . . . . . . . 241 J.1 Version 2 Syntax Changes . . . . . . . . . . . . . . . . . 241 J.2 Version 2 Command Changes . . . . . . . . . . . . . . . . 241 J.3 Icom v1.00 Script Conversion . . . . . . . . . . . . . . . 243 Intellicomm v2.01 SCRIPT.DOC 1 1. SCRIPT COMMANDS AT A GLANCE 1.1 Introduction This section contains a short description of all the commands available in the Intellicomm script language, grouped by command type/purpose. Use this section to locate the command you need, then look up the command in the DETAILED COMMAND SUMMARY (which is sorted alphabetically, by script command) for detailed explanations and examples. If you're viewing this document in the Icom File Viewer, you can quickly locate the Detailed Summary of a command by pressing [Alt-F] (Find), entering the command of interest followed by an underscore (PRINT_) then searching DOWNWARDS. Each command in the Detailed Summary is followed by a line of underscores to allow you to locate a specific detailed command summary quickly. Items beginning with a dollar sign ($) below are not script commands, but rather are "System Variables" which can be used with other commands in the same way that constant paremeters are used (e.g. SEND $PASSWORD, as was used in the introduction of SCRTUTOR.DOC). Some System Variables are "read only" (for informational purposes) and some are "read/write" (you can assign other values to them to change the way Icom works). The System Variables are described in detail in the SYSTEM VARIABLES Appendix following the command summaries. Again, each System Variable in the Detailed Summary is followed by a line of underscores to allow you to find the Detailed Summary quickly. It is not advised that you attempt to memorize anything below. The idea is to just give this section a quick browse every once and a while until you're generally familiar with what is available -- so you'll know what commands (and what type of commands) exist when a need arises later. Immediately skip over commands/variables (or entire sections) you don't anticipate having a need for.... The list is long, and it's important that you make it right through the list, at least once. Keep in mind that most script writers will only need about 10% of the script commands -- don't concern yourself with what you don't anticipate needing. 1.2 Video (Screen) and Cursor Commands BOX displays a box (with border and optional title) on the video display. CLS clears the terminal screen or current WINDOW to a specific color, or to the current screen color ($SCRN_COLOR). CURSORLARGE makes the cursor large (half character height). CURSORSMALL makes the cursor small (underline). CURSORON displays the screen cursor, if hidden. CURSORONOFF turns the cursor on or off. This command (as opposed to CURSORON/CURSOROFF) is intended to be used with a variable ('CURSORONOFF stat' or the like, where 'stat' is a variable holding either 0 or 1). CURSOROFF hides the screen cursor. CURSORPUSH saves the current cursor size, location, and on/off status for later use with CURSORPOP. CURSORPOP restores the cursor to the size, location and on/off status Intellicomm v2.01 SCRIPT.DOC 2 it had when CURSORPUSH was last called. ERASELINE clears a given screen line (row) to a given color, does not move the cursor (use GOTOXY after ERASELINE to move the cursor to the blank line, if desired). GOTOXY moves the screen cursor to specific X/Y coordinates relative to the top corner of the current WINDOW. MSGOPEN displays a message in a centered box on the screen. MSGCLOSE closes the message box opened with MSGOPEN. MSGWIND displays a message in a box, pauses, closes the message box. PRINT displays text in the current video WINDOW using the current $SCRN_COLOR color, adds a CR/LF (which moves the cursor to the beginning of the next line). PRINTNC displays text in the current video WINDOW using the current $SCRN_COLOR color. Similar to PRINT, but doesn't add a CR/LF (NC stands for 'N'o 'C'arriage return). PRINTRAW writes directly to the video display (ignoring the current WINDOW), using a specific color. Much faster than PRINT/PRINTNC or PAUSE. SCREENBLANK activates the Icom screen blanker, if the user has screen blanking activated in the Icom main setup. Screen blanking is done by Icom automatically even when a script is running (as long as $KEY_CHECK is turned on), but if you want to force the screen to blank at some point, before waiting for the usual timeout, you can use this command. SCREENRESTORE restores the screen, if blanked. Again, Icom automatically unblanks the screen by itself in most cases, when your script does something that the user must participate in (such as operating a menu, or getting input, etc). But you can always ensure that the screen is not blanked with this command if need be, before important operations. SCROLL scrolls a given area of the video screen up or down, or clears an area to a specific color. VGETCHR gets the video screen character at the current cursor position, stores it in a variable. VGETCHRS gets a given number of characters from the video screen (at specific x/y coordinates) and stores them in a variable. VPUSH saves an area of the screen (or the whole screen), including color data, for later use with VPOP. VPOP restores the screen saved by the last VPUSH. WINDOW defines a new screen window (given screen x1/y1, x2,y2 coordinates) or restores the terminal to full-screen if no coordinates are specified. Data from the modem, and text you print with the PRINT, PRINTNC, and PAUSE commands will stay within the current WINDOW coordinates. WNDOPEN opens a display window (box) on the screen, saving all screen attributes. A simple call to WNDCLOSE puts everything back the way it was. WNDCLOSE Removes from the video display the last window opened with WNDOPEN. $BAR_COLOR the color defined in the Icom main setup for menu hilight bars. $BOLD_COLOR 'hotkeys' color (menus) and bold text color. $BORDER_COLOR color used for box borders. Intellicomm v2.01 SCRIPT.DOC 3 $NORM_COLOR color used for regular text in boxes/menus. $SCRN_COLOR the CURRENT terminal screen color (at the positon of the cursor). NOTE: BBS ANSI codes can change $SCRN_COLOR. $SCRN_HEIGHT total number of rows (top to bottom) on the real screen, ignoring the current WINDOW. $SCRN_WIDTH total number of columns (left to right) on the real screen, ignoring the current WINDOW. $SCRN_WRAP if non-zero, lines within the current WINDOW (or terminal screen) are wrapped to the next screen line when they reach the end of the window. If zero, lines are truncated (cut) when they reach the end of the window. NOTE: BBS ANSI codes can change the status of $SCRN_WRAP. $SCRN_X current column (x position) of the screen cursor. $SCRN_Y current row (y position) of the screen cursor. NOTE: BBS ANSI codes can change the $SCRN_X and $SCRN_Y positions. $STAT_COLOR status line color. $STAT_ON reports the state of the status line (off is 0, on is 1) and allows you to turn it on and off (ASSIGN $STAT_ON 0 turns it off, ASSIGN $STAT_ON 1 turns it on). $TERM_COLOR the DEFAULT terminal screen color, as defined in the Icom main setup. After BBS ANSI codes have changed your screen color, ASSIGN $SCRN_COLOR $TERM_COLOR to set it back to the default color. $WND_TOP the top screen line of the current WINDOW. $WND_BTM the bottom screen line of the current WINDOW. $WND_LEFT the left screen row of the current WINDOW. $WND_RIGHT the right screen row of the curren WINDOW. $WND_WIDTH the width (number of screen columns available left to right) of the current screen WINDOW. $WND_HEIGHT the height (number of screen rows available top to bottom) of the current screen WINDOW. 1.3 Menu Handling MENUBAR displays the currently defined menu, in 'bar menu' format. MENUBOXH displays the currently defined menu in 'box menu' format. Menu items are displayed Horizontally in the box. MENUBOXV displays the currently defined menu in 'box menu' format. Menu items are displayed Vertically in the box. MENUDEFINE define a menu for use by MENUBAR, MENUBOXH, MENUBOXV. MENUITEMSTAT hide, disable, or unhide/enable one given menu item, in the currently defined menu. MENUHLP attaches a line of help to a given menu item. On horizontal menus (MENUBAR or MENUBOXH) the help line is displayed under the first menu item as in the Icom Job Directory and BBS Directory bottom menus (when you press [Left] or [Right] the help line changes to the selected item). On vertical menus (MENUBOXV) the help line is displayed on the bottom screen line. $MENUSELECTION is set to the menu item number selected by the user (or 0 if [Esc] is pressed) after MENUBAR, MENUBOXH or MENUBOXV. Intellicomm v2.01 SCRIPT.DOC 4 1.4 Keyboard Input and Output BOXGETS displays a box centered on the screen, with optional box title and information line, offers an optional 'default' to the user then gets input (a given number or characters) from the keyboard allowing use of several editing keys ([Del], [Ins], [Left], [Right], [Home], [End], etc) to edit the input. GETS offers an optional default and gets a line of text of a given length from the keyboard. Similar to BOXGETS, but GETS doesn't display a box. The [Enter] or [Esc] key, or left/right mouse button which signify Enter and Esc, must be pressed to terminate both BOXGETS and GETS. GETSXY same as GETS above, but GETSXY gets text at a specific screen X,Y coordinate. INKEY gets a single keystroke from the keyboard (any key; Alt-keys, Function keys, regular keys, etc) and stores the value of the key in a variable. See the KEYBOARD CODES appendix for key values. This command doesn't WAIT for a keystroke; it simply checks for one and stores it if one is waiting. You'd use this one in a WHILE 'loop', if you wanted to do something while waiting for a keystroke... such as updating a clock, or counting something, etc. Use INKEYW to halt script execution and wait for a single keypress. INKEYT same as INKEY above, but INKEYT waits a specified 'Timeout' period for a key to be pressed, and gives up if no keys are pressed in time. INKEYW same as INKEY above, but waits until a key is pressed. Similar to the PAUSE command but INKEYW (and INKEY) stores the key code of the key pressed (i.e. you can check it to see what the user entered) in a given variable. PAUSE displays an optional message, then pauses for a keystroke from the user. The key pressed is discarded. SENDKEY sends (simulates) one or more specific keystrokes to the Icom terminal key handler. Depending on the key(s) you send, this may pop up an Icom menu and select something, or may be sent to the BBS -- whatever would happen if you pressed the key from Terminal mode. If "Doorway Mode" is on, ALL keys other than [Alt-=] (doorway mode on/off) are sent to the BBS. $DOORWAY the current status of 'Doorway Mode'. 0 = Off, 1 = On. If $DOORWAY is ON (non-zero), the regular Icom hotkeys ([Alt-Z] to pop up the terminal menu, etc) are sent to the BBS instead of performing their usual function. Doorway mode is only of use only when $KEY_CHECK (see below) is non-zero, and only with a BBS function or BBS DOOR that supports doorway codes and recognizes the extended key codes. Doorway codes are often supported in online information systems (online encyclopedias, etc) to allow a more advanced user interface with function keys and support for the [Alt] keys, etc. $HOTKEY_? the ? must be replaced with a number from 1 through 5 ($HOTKEY_1, $HOTKEY_2 ... to $HOTKEY_5). These hotkeys, if defined, are watched for by BOXGETS, GETS, and GETSXY to allow you to cancel input when specific keys are pressed WHILE the user is entering something in the input field. For Intellicomm v2.01 SCRIPT.DOC 5 example, the input box Intellicomm displays when prompting for filenames to UPLOAD allows the user to press the [Alt-F] key to display the 'file picker' instead of entering filenames manually. You can do similar things with your own BOXGETS/GETS/GETSXY input prompts by using the $HOTKEY_? variables. See the KEYBOARD CODES appendix for a list of extended keys you can ASSIGN to these hotkeys. Also see the BOXGETS detailed summary for an example of usage. $KEY_CHECK this goes one step further than $DOORWAY, and determines whether ANY keys will be processed by Intellicomm at all. If $KEY_CHECK is set to zero (0), it's up to you to use INKEY or INKEYW to process ALL user keystrokes (please see the notes in $KEY_ALTQ below). $KEY_CHECK is automatically turned back on (set to 1) when the script processor exits. $KEY_FILTER similar to the $HOTKEY_? variables, this is used with GETS/GETSXY and BOXGETS but the characters defined in $KEY_FILTER (if any) are NOT accepted in input fields. For example, if you were getting a filename you might put a space in the $KEY_FILTER using ASSIGN $KEY_FILTER " " which would prevent the user from entering a space during the next BOXGETS/GETS/GETSXY command. You can define up to ten characters to ignore... ASSIGN $KEY_FILTER "*? " would prevent the user from entering asterisks, question marks and spaces in the input field. All characters assigned to $KEY_FILTER must be regular ASCII characters. To filter out control characters, use the caret ("^[" is ESC, "^C" is Ctrl- C, etc). See ASCII CODES in the Appendix for control characters. $KEY_ALTQ if non-zero, Icom checks for [Alt-Q] (abort job or script, turn on script debugging, etc) while your script is running. If you want to prevent the user from aborting the script, ASSIGN $KEY_ALTQ 0 (set it to 0) and Icom will not pop up the Control Menu when Alt-Q is pressed. This should only be used when you have something to clean up when your script ends, such as resetting System Variables or re-loading a BIF or main setup file, etc. If you shut this off, you should substitute your own script abort menu by checking for Alt-Q (key code 4096) after INKEY, INKEYW and/or setting a $HOTKEY_? to Alt-Q (ASSIGN $HOTKEY_1 4096) for BOXGETS, GETS/GETSXY to observe. The best way to handle it is by using a subroutine (GOSUB MY_INKEY, GOSUB MY_INKEYW, GOSUB MY_BOXGETS, etc.) to get keys, then check for Alt-Q (4096) in the subroutine. If the user enters Alt-Q Pop up an "Abort script? Yes No" menu with BOXMENUH. If Yes is selected, call your 'clean_up' subroutine to reset whatever needs resetting, then EXIT. 1.5 Communications CAPTURE closes current capture, if open, then opens a new capture file. CAPCLOSE closes the current capture file, doesn't open a new one. CAPPUSH saves the current capture D:\PATH\FILENAME.EXT, and status (open, closed, paused), for later use with CAPPOP. CAPPUSH Intellicomm v2.01 SCRIPT.DOC 6 saves the capture filename/status only ONCE. If you call it again before using CAPPOP, you lose the previous CAPPUSH data. CAPPOP restores the capture filename and status (open/closed/paused) to the value they had when CAPPUSH was last called. CAPSTAMP stamps a line in the capture file (if open) containing the current date, time, BIF ID and BBS/Host Name. CGETC gets a character from the current COM port and stores it in a variable. If no characters are available, CGETC waits until a specified timeout has elapsed (or indefinitely if no timeout is given). CGETS gets a 'string' of characters from the COM port, and stores it in a specified variable. CGETS also takes an optional 'end- of-string' character and timeout, and it returns control only after a Carriage Return (CR) is received, or the specified end-of-string character is received, or the timeout elapses. DIAL dials one or more BBS Information Files, or a specific phone # (similar to the "Manual" dial option in the BBS Directory), or displays the BBS Directory for manual user input. DOWNLOAD downloads one or more files using a specified protocol. HANGUP same as pressing [Alt-H] from Terminal mode... tells the modem to disconnect. INITMODEM same as pressing [Alt-I] from Terminal mode... sends the "Initialize Modem" string, defined on the main setup/Terminal screen, to the modem. LOG opens a new usage log file (the default usage log is \ICOM\CAP\ICOM.USE). LOGCLOSE closes the usage log, if open. Once closed, Icom will not write usage data of any sort. NEWAREA uses the commands and prompts defined in the currently loaded BIF to change to a new area of the BBS. You can change to the Main Menu, Message Menu, Bank Menu, File Menu, or change file areas/message areas ([J]oin a conference, etc). If the area change is unsuccessful, $ERRORLEVEL is set. There are some considerations for using this command properly, which are outlined in the DETAILED COMMAND SUMMARY. OFFLINE if the modem is not connected, a command is carried out. ONLINE if the modem IS connected, a command is carried out. PORT changes to another COM port (current port is closed first... you'll lose the connection if connected). REDIAL used after DIAL to re-dial any BIFs that remain tagged. RXBUF tells you how many (if any) characters are waiting in the receive buffer. See below. RXFLUSH empties the Icom receive buffer. Characters received from the COM port that have not been processed yet (CGETC, CGETS, SEND, SENDBIF, SENDNC, WAITFOR, and TERMINAL are the only commands that process incoming characters from the port) will pile up in the receive buffer. If you aren't expecting (or don't need) input from the port at a given point in your script, or if you want to clear any line noise before an operation, use RXFLUSH to get rid of garbage. SCROLLBACK same as pressing [Alt-B] from Terminal Mode. Enters the scrollback buffer. SEND sends text out the current COM port (to the BBS), and follows it with a Carriage Return (CR, same as pressing the [Enter] Intellicomm v2.01 SCRIPT.DOC 7 key). If a "Response Delay" is defined in the current BIF, SEND delays sending of the data for the duration of the Response Delay. SENDNP SEND with No Pause. Same as SEND above, but doesn't observe the BIF Response Delay. SENDNCP SEND No CR or Pause. Same as SEND above, but never adds a CR, and doesn't observe the Response Delay, SENDBIF sends a specific BIF command out the current COM port, or runs a @SCRIPT, or executes a !DOS command, as BIF commands are entitled to do. If "CR w/Commands?" on BIF screen 1 of the current BIF in use is set to "Yes", then a CR is added after the response. Otherwise, no CR is added (BBS hotkeys), just as with Icom's automated routines. SENDBIF is exactly what Icom uses to handle BIF responses during automated jobs. SENDBREAK sends a break signal to the current COM port. On error- correcting modems, a break usually clears the modem transmit buffer (a good way to flush data after a cancelled transmit operation). SENDNC same as SEND, but doesn't add a CR. SETCOMM changes the current COM port settings (baud, parity, etc). SHOWWHENS shows the currently defined WHENs, and the command (up to 20 characters) that will be executed WHEN the text is found. Mainly for debugging BIFs and automated jobs to see which BBS prompts Icom is tracking during a given job. STAMP stamps a COMMENT record in the Usage Log, if open. TERMINAL is an advanced command that will only be needed if your script fails to display characters from the BBS and doesn't allow keys to be processed ([Alt-Z] to pop up the Terminal menu, etc). If you run into this problem, look up TERMINAL's details in the Detailed Command Summary. TXBUF tells you how many (if any) characters are waiting to be sent to the modem (COM port) in the transmit buffer. See next. TXFLUSH clears characters waiting to be sent to the modem from the transmit buffer. SEND, SENDBIF, SENDKEY, and SENDNC send characters to the transmit buffer. When the modem is ready to send, characters are moved from the transmit buffer to the COM port (where the modem then takes them and sends them to the BBS). Use TXFLUSH to get rid of any characters sitting in the transmit buffer. UPLOAD uploads one or more files using a specified protocol. WAITFOR handles WHENs (if any) while waiting for specific text from the current COM port. An optional timeout can be specified with an optional script label to GOTO if the text isn't found. WHEN defines text to watch for (and handle with a specific command, if found) while WAITFOR is active. Also used to clear previously defined WHENs. $BBS_AREA is set to a letter, enclosed in square brackets, reflecting the current BBS Area (Main Menu, Message Menu, Bank Menu, or File Menu, or 'location unknown' if blank), for use mainly when calling scripts from automated jobs. When your script starts you can check the current area by checking $BBS_AREA, and can move to a new area if need be with the NEWAREA command. $BBS_AREA will only be set to an area if Intellicom was AT the main menu of the area when your script was called. Intellicomm v2.01 SCRIPT.DOC 8 $CARRIER the state of the DCD signal (carrier detect) on the current $COM_PORT. If 0 (zero), the modem is reporting offline (not connected). If non-zero the modem is reporting online (connected). See "Common Questions & Answers" in the Icom online help for a fix if your modem isn't telling the truth and reports online always. $COM_PORT the number of the current COM port (1-8; 1 = COM1, etc). $COM_SPEED the current speed (baud rate) of the COM port (300-115200). $SEND_CR a flag (zero is 'off', non-zero is 'on') that determines whether the SEND command adds a Carriage Return (CR; the same as pressing [Enter]) after the data it sends. 1.6 Icom Information / Script Variables ASSIGN assigns text or numbers to a variable. GETENV gets DOS environment data (PATH, PROMPT, etc) and stores in a variable. SETENV changes, sets, or clears a DOS environment variable (PATH, PROMPT, etc., or an environment variable you're using to keep track of specific information). VARIABLE defines a variable name and allocates storage space in memory. You can also assign data to the variable when defining it. $BETA_VERSION the current beta version of Intellicomm (or 0 if a production release). $BIF_DIR the BIF directory (where .BIF files are found). $BIF_NAME the filename of the currently loaded BIF (no extension; it's always .BIF). $CAP_NAME the current capture file (D:\PATH\FNAME.EXT). $CAP_STAT the current status of the capture file (0 = closed, 1 = open, 2 = paused). $CAT_DIR the Catalog Directory (File Tagger databases) as defined in the Icom main setup. $CAT_NAME the name of the currently open Catalog (if open). $DSEP the 'Date Separator' character as defined in the Icom main setup. $DL_DIR the current Download Directory (BIF or main setup if no Download Dir defined in the BIF). $DL_PROTOCOL the "Receive Files" protocol, as defined in the current BIF. $ERRORLEVEL set to specific numbers by commands (see ERRORLEVEL sections in the Detailed Command Summary). $FULL_SCRIPT_NAME the full D:\PATH\FILENAME.EXT of the currently executing script. Also see $SCRIPT_NAME. $HOME_DIR the Icom home directory (where ICOM.EXE is, or where the ICOM environment variable points to). $LST_DIR Icom List Directory (main setup option defaults to \ICOM\LST). This is where Icom looks for .NEW files lists to auto-import to the Tagger catalogs. $MAJOR_VERSION Intellicomm major version number (2, 3, etc). $MINOR_VERSION Intellicomm minor version number (0 1 10, etc.) after the decimal. Icom v2.10 would have a $MAJOR_VERSION of 2 and a $MINOR_VERSION of 10 (ten). $MSG_DIR the current Message Directory (BIF or main setup if no BIF Intellicomm v2.01 SCRIPT.DOC 9 Message Dir defined). $MSG_PROTOCOL the "Receive Messages" protocol, as defined in the current BIF. $PASSWORD the logon password defined in the current BIF. $PRN the printer device defined in the main setup (defaults to PRN). $REP_DIR the current Reply Directory (BIF or main setup if no BIF Reply Dir defined). $REP_PROTOCOL the "Send Replies" protocol, as defined in the current BIF. $SCRIPT_DIR the Icom Script Directory, as defined in the main setup. $SCRIPT_NAME the FILENAME.EXT of the current script (no D:\PATH\ ... use this when simply want to print the script name for user consumption). $TSEP the 'Time Separator' character as defined in the Icom main setup. $UL_PATH the full Upload PATH (BIF or main setup if no BIF path Upload PATH defined). Upload PATHs are in the format: D:\DIR1;D:\DIR2 etc. Use STRITEM to obtain a specific directory from the path. $UL_PROTOCOL the "Send Files" protocol, as defined in the current BIF. 1.7 Text (String) Handling ADDSLASH checks a variable containing text (usually a directory name) to see whether it has a trailing backslash (\) or not. If it does have a trailing backslash, nothing is done. If it doesn't have a trailing backslash, a backslash is added. EXCEPTION: if the variable contains only a drive letter (C:), a slash is not added. SETCHR puts a single character into a string, at a given point, overwriting the previous character. SETCHRS copies one string into another, at a given point, overwriting the original string portion. STRBLANK checks to see if a variable is blank (empty or all whitespace*). STRCHR finds the first occurrance of a given character in a given string (case sensitive) and stores the position of the character in a variable. This command is most likely to be used in combination with another of the string handing functions, such as STRINS or STRDEL. STRCHRI same as STRCHR, but case (UPPERCASE/lowercase) of the character searched for is ignored. STRCPY copies one string (or a portion) to another at a given position. STRDEL deletes a given number of characters from a given position in a variable. STRITEM gets a specific item from a variable (see detailed summary). STRLOWER converts text in a variable to lower case. STRCAT adds (concatenates) one string to the end of another. STRINS inserts a given number of characters from one string to a given position in a variable. STRCAT adds text only to the end of a variable. Use STRINS to add text at any position. STRLEN gets the length of a given constant or variable (check the length of a string). STRPAD pads a variable (with any character) to a given length. Pad Intellicomm v2.01 SCRIPT.DOC 10 characters are added to the RIGHT side of the variable. STRPADL pads a variable (with any character) to a given length. Pad characters are inserted on the LEFT side of the variable (useful for lining numbers up; right justified). STRSET sets a given number of characters in a variable (at a given positon) to a given character. STRPOS looks for a substring in another string, stores the position (if found) in a variable. Case IS sensitive. STRPOSI is the same as STRPOS, but case is not sensitive. STRRCHR searches a given string from the last character towards the first, for a given character (case sensitive). STRRCHRI searches a given string from the last character towards the first, for a given character (case insensitive). STRREPLACE replaces all occurrances of one string in another (case sensitive). STRREPLACEI replaces all occurrances of one string in another (case insensitive). STRSTRIP strip all occurrances of a given character from a given variable. The character, if found, is not replaced with another character; text from the right is simply pulled over to overwrite the character until the character no longer exists in the string. Use to simply eliminate unwanted characters from text, such as commas, spaces, etc. STRTRIM trims whitespace* from the right side of a string. STRLTRIM trims whitespace* from the left side of a string. STRBTRIM trims whitespace* from both the left and right side of a string. STRUPPER converts text in a variable to upper case. SUBSTR copies a portion of one variable to another variable. * Spaces, tabs, and Carriage Return/Line Feed characters are 'whitespace'. 'White' because when you send these characters to a printer they leave white space on the paper. 1.8 Math Commands ADD adds two numbers and stores the result in a variable. AND is an advanced command for programmers. If performs a bitwise AND on two numbers, and stores the result in a variable. If you don't know what a bitwise AND is, you won't need this command. DIV divides two numbers, stores the result in a variable. DEC (DECrement) subtracts 1 from the contents of a variable (x = x - 1). INC (INCrement) adds 1 to the contents of a variable (x = x + 1). INC and DEC are used mainly for counting. OR is an advanced command for programmers, similar to the AND command above. It performs a bitwise OR on two numbers and stores the result in a variable. If you don't know what a bitwise OR is, you needn't concern yourself with this command. MUL multiplies two numbers, stores the result in a variable. SHL (SHift Left) is also an advanced command for programmers which shifts a given number of bits in a number towards the left. The result is stored in a given variable. Each bit shifted to the left has the effect of multiplying the original number by two (2). SHR (SHift Right) is another an advanced command for programmers which shifts a given number of bits in another number towards the right. Intellicomm v2.01 SCRIPT.DOC 11 The result is stored in a given variable. Each bit shifted to the right has the effect of dividing the original number by two (2). SUB subtracts one number from another, stores the result in a variable. XOR is similar to AND/OR above, but performs a bitwise eXclusive OR on two numbers and stores the result in a variable. This one, while it's also mainly for programmers, can actually be quite useful to non-programmers and it's worth a looksee in the Detailed Summary. 1.9 DOS and File Input/Output Commands APPEND adds the contents of one text file to the end of another text file (the original file remains intact). APPENDS adds one line ('S'tring; a script variable or constant) to the end of a text file. Terminates the line with a Carriage Return (CR) and Line Feed (LF) and closes the file. APPENDSNC same as APPENDS, but doesn't add CR/LF to terminate the line (NC stands for 'N'o 'C'arriage return). CHDIR changes DOS's 'current directory' (same as CHDIR from DOS). COPY copies one file (text or binary) to another filename and/or directory. Overwrites files of the same destination name (use APPEND to add one file to another). Similar to the DOS 'COPY' command. DEL/DELETE delete a file on-disk. Similar to the DOS 'DELETE' command, and wildcards (* and ?) are accepted in the filespec. Be careful with this one ... DELETE "*.*" doesn't ask you to confirm before it deletes all files in the directory. DIRFIND looks for a directory on-disk, executes a script command if it DOES exist. This command is similar to EXIST, but looks for a directory instead of a file. DISKFIND searches all directories on a given disk for a given filespec (* and ? accepted). If the file is found its full drive/pathname (D:\DIR\FILENAME.EXT) is stored in a given variable. DISKFREE stores the amount of free disk space on a given disk in a given variable. DOS executes a DOS command (or runs another program or .BAT file) or performs a DOS shell. EXEC similar to the DOS command above, but EXEC does not use the command processor (COMMAND.COM) to execute the given command. EXEC is used when you need the 'errorlevel' reported by a .COM or .EXE. Most of the COMMAND.COM features (running .BAT files, executing commands such as COPY, etc) are not supported by EXEC. Simple redirections (> or >> to redirect program output to a file or device) are supported by EXEC if you need them, but pipes (|) and input redirection (<) are not supported. Use the 'DOS' command above for those. EXIST looks for a file on-disk, executes a script command if it DOES exist. This command also sets the file attribute System Variables listed below, if a file is found. FCLOSE closes a file previously opened by FOPEN. FFLUSH flush (write) any data in the write buffer of an open file. FGETC gets one character from an open file. FGETS gets one line from an open file. FNSTRIP takes a given filename and removes various components (drive Intellicomm v2.01 SCRIPT.DOC 12 only, drive and filename only, path only, etc). FILESIZE puts the size of a file in a variable, if the file is found (wildcards are accepted). Also sets the file attribute System Variables listed below. FINDFIRST locates the first file matching a given filespec and set of file attributes (*.SCR, *.*, hidden files, read only files, subdirectories only, etc) and stores the filename in a given variable. This command also sets the file attribute System Variables listed below, if a file is found. FINDNEXT locates the next matching file after a FINDFIRST and stores the filename in a given variable. This command also sets the file attribute System Variables listed below. FOPEN opens a file for appending, reading, writing or read/write. FPUTC writes a character to an open file. FPUTS writes a line to an open file, following it with a Carriage Return (CR) and Line Feed (LF). FPUTSNC same as FPUTS but doesn't add CR/LF to the end of the line. FSEEK seeks to a specific position (byte) in an open file. FTELL reports the current position (byte) of an open file. GETFNAME displays all files matching a given filespec, and allows the user to "Select" one or more files for your script to operate on. Useful whenever you must get one or more filenames from the user. LOCATEFILE searches the current Download Dir, Upload PATH, and the DOS PATH (if "Use PATH to locate files" is turned ON in the Icom main setup) to locate a given filespec (* and ? accepted). If the file is found, its full path is stored in a given variable. MKDIR makes a new disk directory. NOTEXIST looks for a file (or filespec) on-disk, executes a script command if it DOESN'T exist. If the file does exist, this command also sets all the file attribute System Variables listed below. RENAME rename or MOVE a file (from one directory to another) on-disk. RENUMBER Renumbers a given set of files, similar to the Capture file renumbering (ICOM.CAP, ICOM01.CAP, ICOM02.CAP, etc). RMDIR remove (delete) an empty disk directory. SCAPTURE writes (appends to, if the file exists) a snapshot of the screen to a given file (or the Screen Capture file \ICOM\CAP\SCREEN.CAP by default if no filename specified). $CURDIR the current DOS directory. The following System Variables are set by the EXIST, FILESIZE, FINDFIRST, FINDNEXT, and NOTEXIST commands, if the specified file file/filespec exists. If the file doesn't exist all except $FSIZE are set to 0 ($FSIZE is set to -1). Note that these variables are set to the attributes of the currently executing SCRIPT when a script begins. So if you want to check the script size or modification date (or any other attribute) just access these variables at script startup, before you use EXIST, FILESIZE, FINDFIRST, FINDNEXT, or NOTEXIST: $FDAY file modification date, day of month (0-31). $FMONTH file modification date, month (1-12). $FYEAR file modification date, full year (1993, etc). Intellicomm v2.01 SCRIPT.DOC 13 $FHOUR file modification time, hour (0-23). $FMIN file modification time, minute (0-59). $FSEC file modification time, second (0-59). $FSIZE size of the file, in bytes. $FRDONLY read-only attribute (will hold + if set, - if clear). $FHIDDEN hidden attribute (+ if set, - if clear). You must use FINDFIRST/FINDNEXT to find hidden files. $FSYSTEM 'system file' attribute (+ if set, - if clear). You must use FINDFIRST/FINDNEXT to find system files. $FVOLID Volume ID attribute (+ if set, - if clear). This will only be set on one file in the root directory. You must use FINDFIRST/FINDNEXT to find the Volume ID. $FSUBDIR subdirectory attribute (+ if set, - if clear). I.e. this is not a file, it's the name of a subdirectory. You must use FINDFIRST/FINDNEXT to find subdirectories. $FARCH archive attribute (+ if set, - if clear). If the archive attribute is +, the file has been changed since the last disk BACKUP (most backup programs clear the archive attribute after the file is backed up. DOS sets it again if you modify the file or create a new file). 1.10 Date and Time TIMER starts a timer and sets it to expire after a given number (tenths of a second). TIMERTOTAL the total time elapsed (in tenths of a second) since TIMER was last called. TIMEUP checks the timer started with TIMERSTART to see whether it has expired. If it has, the script command following TIMEUP is executed. $DATE the current system date in text format (MM/DD/YY or the format defined by the user in the Icom main setup). $DAY current day of month (1-31) $DOW current day of week (1-7) $HOUR current hour (0-23) $HSEC current hundredth of a second (0-99) $MIN current minute (0-59) $MONTH current month (1-12) $SEC current second (0-59) $TIME the current system time in text format (HH:MM:SS or the format defined by the user in the Icom main setup). $YEAR current year (1993, etc.) 1.11 Script Flow / Decision-Making IF compares two items (usually one or both items being variables) for equality, inequality, greater than/less than, etc. IF has two incarnations. If you specify another script command after the IF comparison, the specified command is executed if the comparison is TRUE, and is skipped if the comparison is FALSE. If no command is specified after the IF comparison, it is assumed you are using an IF/ELSE/ENDIF sequence, which allows you to execute one SET of commands if the comparison is TRUE, and another SET of commands if the comparison is FALSE (the Intellicomm v2.01 SCRIPT.DOC 14 commands after the ELSE, if ELSE is used). CHECKVERSION takes a version number in the format "x.xx" ... or "x" ... or "x.x" (e.g. "2.00", "2", "2.0", etc) and compares the numbers to the current Intellicomm version number. If the Icom version number is less than the version number (or portion of the version number) you specify, the script aborts with the error message: "Sorry, this script requires Intellicomm vx.xx or above." (where x.xx is the version number specified in CHECKVERSION). DELAY pauses your script; allows incoming characters from the BBS to be displayed during the pause. DELAYNC pauses your script; DOESN'T allow incoming characters from the COM port to be displayed. EXIT ends the script with optional error return code. See the detailed summary before using this command with an error return code. GOSUB turns control over to a subroutine temporarily. Similar to GOTO, but GOSUBs are temporary, and they RETURN control to the command following the GOSUB (or back to the WAITFOR if called from a WHEN) when they're done. GOSUB is especially useful in WHEN commands to have more than one command carried out when BBS text is found. GOTO jumps to a 'label:' without returning. RELOADSCRIPT reloads the current script from disk and starts running it at the beginning again. RETURN returns from a subroutine, or back to the caller (whatever started the script) if used after a GOSUB. SCRIPT runs another script then returns control to the calling script. Similar to GOSUB, but runs another script as the subroutine. SWITCH executes one or more script commands based on a given condition. CASE specifies a condition. ENDCASE denotes the end of one condition (mandatory). ENDSWITCH denotes the end of the SWITCH statement (mandatory). SYSTEM exits Intellicomm (after closing the port, etc., and either hangup up, staying connected, or prompting whether to hang up) back to DOS with an optional DOS 'errorlevel'. WAITUNTIL displays a box on the screen showing the time and/or day to WAITUNTIL, along with the current date and time, and a list of menu options (complete with a screen blanker) then pauses the script until the specified time and/or day, or until the user aborts the pause. WHILE executes a set of commands WHILE a condition remains true. BREAK exits a WHILE 'loop'. CONTINUE jumps back to the top of a WHILE 'loop' (check condition again). ENDWHILE denotes the end of the WHILE loop (mandatory). 1.12 Other Useful Commands ALARM sounds an alarm on the PC speaker to get the user's attention, but only if the System Variables $ALARMS and $SOUND are non- zero. If $ALARMS *or* $SOUND are set to zero, the ALARM is Intellicomm v2.01 SCRIPT.DOC 15 ignored. Icom automatically sets $ALARMS to 0 before running automated jobs. You can change the value of $ALARMS and/or $SOUND by ASSIGNing 0 (off) or 1 (on) to them. BEEP sounds a beep on the PC speaker to get the user's attention, but only if the System Variable $SOUND is non-zero. If $SOUND is set to zero BEEP (all sound) is ignored. Icom automatically sets $SOUND to 0 before running automated jobs. CHAT enters into Chat Mode. Control returns to the script when the user is finished chatting and presses [Esc] to exit Chat Mode. DEBUG turns the script debugger on or off. EDIT loads a text file for editing, positions to optional line #. FILEMAN calls the Icom File Manager to display a given directory and/or filespec. The user can Edit, View, Copy, Ren/Move, Delete, Find files, or display another directory. Control returns to the script when the user exits the File Manager. HELP displays a specific help topic (or the help index). HELPFIND similar to using the online help "Search" feature. It searches all topics in the online help file for a given keyword, and displays all topics that contain the keyword to the user. LIST displays a text file for viewing, positions to optional line #. LOADBIF loads a new BIF into memory. LOADINI loads a new main setup (.INI) file into memory. SAVEBIF saves the current BIF information (in memory) to disk. SAVEINI saves the current main setup data (in memory) to disk. TAGGER enters the File Tagger, loading a specified catalog for viewing. TONE sounds a specific tone on the speaker, for a specific duration. $ALARMS determines whether alarms are heard or not (this is a main setup option and is used globally in Intellicomm). $OPSYSTYPE reports the Operating System in use on the computer (DESQview, DOS, OS/2 or Windows). $SOUND determines whether any sound at all is heard (beeps from the BBS, ALARMs, etc. This is also a main setup option). GlobalStr[] is a global variable 'array' available to all scripts. The GlobalStr array stores parameters (if any) passed to a script from DOS, Custom Commands, BIFs or other scripts, and is otherwise useful for simply storing information semi- permanently (for the duration of the Icom session) and for other useful things. See SCRTUTOR.DOC for more details on GlobalStr. 1.13 File Tagger Commands (Advanced use only) These commands allow you to manipulate File Tagger catalogs (databases) directly, and are for advanced script writers only. Read INTRODUCTION TO DATABASE COMMANDS in SCRTUTOR.DOC before using these commands. CADDREC adds a new record to the currently open (COPEN) catalog, and updates the NDX's (indexes, used to sort catalogs) to include the new record's data. CCLEARBUF clears all $CXXXX_FLD variables and the record description buffer. CCLEARDESC clears only the record description buffer. CCLOSE closes the currently open catalog. CDATE2DATE converts a dBASE date (YYYYMMDD ... as dates are stored in Intellicomm v2.01 SCRIPT.DOC 16 catalogs) to the date format defined by the user in the Icom main setup. [For displaying dates to the user.] CDATEDIFF takes two dates in dBASE date format (YYYYMMDD) and stores the difference (in days) between the two dates in a given variable. CDELREC delete or undelete a given record. This command doesn't actually remove the record from the database, it simply marks a given record's status for the next CPACK (which actually removes all deleted records). CEDITREC displays the current record obtained with CGETREC for editing. This displays the same editing screen you see when you select "Edit" to edit a record from within the Tagger. As well as being useful for record editing, this command can be useful for debugging, since it shows you last record obtained with CGETREC. Once in edit mode the user can press [PgUp], [PgDn], to browse through the catalog, just as in edit mode. Control is returned to your script when the user presses [Esc] to exit edit mode. CEMPTY executes a given command if the database opened with COPEN is empty (e.g. CEMPTY RETURN, CEMPTY GOTO DONE, etc). CEXPORT exports files in the currently open (COPEN) database to a given text filename, in a given BIF format. If the catalog is currently sorted (CSETSORT), the $VIEW_DATE is observed when exporting records (i.e. you can export only file newer than a given date by setting $VIEW_DATE). CFLUSH writes any data in the CPUTREC, CPUTDESC buffers to disk. CFORMATDESC re-formats the current file comment/description to a new line length. CGETREC automatically formats file comments to a line length of 45 characters. Use this command to make comment lines longer or shorter. CGETDESC gets a given line from the file comment/description field. Use CGETREC to get a record from the database before CGETDESC. CGETREC gets the next (or first, if no prior calls to CGETREC) record from the currently open catalog, and stores the record data in the System Variables listed below. CIMPORTNEW imports *.NEW files lists (captured via your script, or by an automated job) into the proper File Tagger catalog(s). The base filename of the .NEW list must be the same base filename of the .BIF where the list was obtained. CIMPORTTEXT imports a given text file (BBS file listing) into the currently open catalog, using a given BIF file list format. CNOTEREC toggles the 'Noted' status of the current record and updates the NDX's (indexes) with the new data. Similar to hilighting a record from within the Tagger and selecting "Note" from the bottom menu. COPEN opens an existing File Tagger catalog, or creates a new one if the catalog doesn't exist. Only the filename (no extension or directory) is needed. CPACK packs a given database (or the currently open database if one is open and no catalog name is given), removing all records flagged as "Deleted". Also packs the .DBT (file comments that are no longer attached to a valid record) and rebuilds the .NDX files associated with the catalog. Intellicomm v2.01 SCRIPT.DOC 17 CPURGE purges the catalog, deleting records older than the number of days set by the user in the Icom main setup/Tagger settings. "Deleted" records are simply flagged as deleted. They are not removed from the catalog. You must CPACK to physically remove purged records. CPUTDESC updates a given file comment line with new data. CGETREC gets the entire comment (all lines are stored in a memory buffer) and formats it to 45 characters per line. CFORMATDESC re-format the comment to any number of characters per line. CGETDESC gets individual lines from the comment... and CPUTDESC is used to replace ONE description line with new data. CPUTREC updates an existing record with new data. CGETREC stores record data in the System Variables listed below. If you modify any of the data (in memory) you must CPUTREC to write the changes to disk. CSAVEBMARK saves a new 'bookmark' in the currently open catalog, or clears the existing bookmark. The bookmark is where the Tagger hilight bar automatically seeks to when the catalog is displayed. CSAVESORT saves the current sort order and direction (set with CSETSORT) in the currently open catalog header. The saved sort order/direction will be in effect the next time the catalog is COPENed or viewed in the Tagger. CSAVEVDATE saves a new 'view date'. The View Date is observed by the File Tagger in browse or edit mode, and only files that were imported on or after the current View Date are displayed. Similarly, CGETREC only gets records imported on or after the View Date, if the catalog is sorted (CSETSORT). Setting a $VIEW_DATE temporarily is done by simply ASSIGNing the $VIEW_DATE variable a new date. To actually store a new View Date in the catalog (so the Tagger will observe it the next time the catalog is opened), you must CSAVEDATE to update the catalog on-disk. Tagged records are unaffected by the View Date, and 'Noted' records are also unaffected by the View Date if the user has that option turned on the the Icom main setup/Tagger settings. CSEEK allows you to seek to a specific record in the catalog (if no sort order is set with CSETSORT), or to a 'relative' position according to the sort order and $VIEW_DATE (top, bottom, 10 records back from current position, 100 records ahead from current position, etc). CSETSORT set the current sort order to 1 (sorted by Tag Status/ Location), 2 (Catalog Date/Filesize), 3 (Filename/File Date) or -1 (unsorted). Also set the direction of the sort (forwards or backwards). The current sort order is observed by CGETREC, and CSEEK. CTAGALL Tag, Note or Untag all records in the currently open catalog. The $VIEW_DATE is ignored; ALL records are game. CTAGREC toggles the tag status of a given record (or the current record obtained with CGETREC if no record # specified). Updates the indexes (sorting information) with the new data. CTELL report the current record number (last obtained with CGETREC). Intellicomm v2.01 SCRIPT.DOC 18 DATE2CDATE Converts a date (see $DATE) in the format the user has set up in the Icom main setup, to a dBASE-style date (YYYYMMDD). UPDATEDNDX updates DOWNLOAD.NDX with any new files that were DOWNLOADed. Files listed in DOWNLOAD.NDX are never added to BBS file listings (provided that the 'Use DOWNLOAD.NDX' item is turned on in the main setup). To update the directories scanned for downloads, see the main setup/Tagger section "DOWNLOAD.NDX Directories" option. $CAT_DIR the Catalog Directory as defined in the main setup (where Tagger catalogs are stored and created). $CAT_NAME the filename of the currently open catalog (no extension). E.g. NEWFILES, FILELIST, etc. $CSORT_DIR current sort direction (0 = forward, 1 = reversed) $CSORT_ORDER current sort order (-1 = Unsorted, 1 = Tag Status/Location, 2 = Catalog Date/Filesize, 3 = Filename/File Date). $CTOTAL the total number of records in the catalog, ignoring the View Date. $CVTOTAL the total number of records in the catalog currently visible according to the current View Date ($VIEW_DATE). This variable is set when you open a catalog, and is re-calculated if you change the $VIEW_DATE variable. $VIEW_DATE the current catalog $VIEW_DATE in the format YYYYMMDD. COPEN automatically sets this variable to the View Date stored in the catalog (as defined by the user; or as defined by Intellicomm's last import if Auto View Date Update is turned on in the main setup). If the catalog is set to use an index with CSETSORT then CGETREC and CSEEK observe the date in $VIEW_DATE, and only operate on records that were imported ($CCDATE_FLD) on or after the View Date. Records imported prior to the View Date are ignored. The following variables are set by CGETREC when it obtains a record: $CREC_STAT the status of the record ("A" = Active, "D" = Deleted). $CTAG_FLD is set to "T" if the file is tagged, "N" if the file is Noted, or blank if neither. $CPRIORITY_FLD the 'transfer priority' (a number from 1-200) of the currently loaded catalog record. $CNAME_FLD the File Name field in the format FILENAME.EXT. $CFDATE_FLD the File Date field in the format YYYYMMDD. $CSIZE_FLD the File Size field. $CCDATE_FLD the Catalog Date field in the format YYYYMMDD (the date that a record was imported to the catalog). This is what $VIEW_DATE compares to, in order to filter out older records. $CLOC_FLD the BIF/Location field (base name of the .BIF needed to download the files. LOADBIF $CLOC_FLD loads the proper BIF if necessary). $CAREA_FLD the BBS Area (conference) the file is in (NEWAREA $CAREA_FLD accesses the proper area if necessary). $CDAY_FLD the Transfer Day set for this file (0 = Anyday, 1 = Sunday, 2 = Monday, etc). Use $DOW to get the current day of the week for comparison. $CFLAG_FLD a general purpose flag field that EACH catalog record has, that you can put to any use you see fit in scripts. Intellicomm v2.01 SCRIPT.DOC 19 Intellicomm v2.01 SCRIPT.DOC 20 2. USING THE DETAILED COMMAND SUMMARIES !!PLEASE READ THIS INTRODUCTION!! This section lists all the script commands in alphabetical order, giving detailed information about each command. If you haven't looked at the section on SCRIPT VARIABLES yet, you should read at least the first couple of paragraphs so you'll know what variables are. Variables are used in many of the examples below, and are referred to frequently in the command descriptions. The Command Summaries require some explanation before you use them. For each script command you will find the COMMAND itself, a SUMMARY showing any parameters the command takes, a DESCRIPTION outlining what the command's purpose is, the ERRORLEVELs the command will set (if any), a SEE ALSO section which points out similar script commands (if any), and an EXAMPLE showing how the command can be used in a real script. 2.1 COMMAND Description The COMMAND itself is listed first, followed by a line of underscores. 2.2 SUMMARY Description Following the command is the SUMMARY, which quickly shows whether any parameters are accepted, what parameter format is expected (string, number, or command), and whether the parameter is mandatory or optional. You'll never use a script command exactly as it's outlined in the SUMMARY section. For example, the BOXGETS command (displays a box and gets a string from the keyboard) has the following summary: SUMMARY BOXGETS vDATA nMAXLENGTH [sTITLE] [sHELPLINE] You wouldn't actually put this in a script, specifying vDATA, etc., every time you used BOXGETS. These are simply conventions used in all the SUMMARY sections, which quickly show you: 1. Whether any parameters are accepted. Above you can see that BOXGETS takes at least 'some' sort of parameters, even though you might not understand exactly 'what' as yet. 2. It shows you which, if any, parameter(s) are optional. Optional parameters are enclosed in square brackets and if you omit the parameter some default value is assumed. The only way to tell exactly what default value will be used is to read the DESCRIPTION of the command (just below the SUMMARY section). 3. It shows you what TYPE of parameters are expected, and, in general, what purpose the parameter serves. The first letter of the parameter (always lowercase) shows you the type of parameter expected, while any characters that follow (always UPPERCASE) simply provide a short description of the purpose the parameter serves. The BOXGETS command expects a 'v'ariable as the first parameter, a 'n'umber as the second Intellicomm v2.01 SCRIPT.DOC 21 parameter, and 's'trings (text and/or numbers) for the rest of the parameters. Following is a list of the various parameter types used in the SUMMARY sections below: cPARAMETER If a parameter begins with a lowercase 'c', then the script command expects another script COMMAND as the parameter. This parameter type is used only by decision- making commands, such as ONLINE, OFFLINE, WHEN, etc. nPARAMETER If a parameter begins with a lowercase 'n', then the script command expects a NUMBER (either a constant number or a variable holding a number) as the parameter. sPARAMETER If a parameter begins with a lowercase 's', then the script command expects a STRING (either a constant string in double quotes, or a variable holding a string) as the parameter. When a string parameter is expected, you can also get away with specifying a numeric parameter (PRINT 1 is the same as PRINT "1"). vPARAMETER If a parameter begins with a lowercase 'v', then the script command expects a VARIABLE as the parameter. This will only be true of one parameter per command, and it's always the first parameter following the command. It's used by commands that assign new data (ADD, GETS, etc) to script variables. [PARAMETER] If a parameter is in square brackets, then it is OPTIONAL. ... If three periods follow all parameters, then the script command accepts a variable number of parameters which can be either strings or numbers. This is normally used with commands that display data to the screen (or write it to a text file) to allow you to print the contents of one or more variables among some constant text. For example: VARIABLE s "is" VARIABLE n 1 PRINT "This " s " text line " n The above would print 'This is text line 1' (no quotes). It's just a convenience, and it allows you to avoid doing this: PRINTNC "This " ;PRINTNC doesn't add a CR PRINTNC s PRINTNC " text line " PRINT n Any time you see three periods following all parameters in the SUMMARY sections below, it means that the command will group together all parameters you specify (up to the maximum script line length of 256 characters). 2.2.1 How to Specify Parameters Constant strings (in quotes) and constant numbers are NEVER mandatory. You can always substitute ANY script parameter with ANY type of script Intellicomm v2.01 SCRIPT.DOC 22 variable: PRINT my_variable ;user defined variable (VARIABLE command) PRINT $DATE ;System Variable PRINT GlobalStr[5] ;Global array member (see SCRTUTOR.DOC) PRINT GlobalStr[my_variable] ;Global member indexed by my_variable PRINT *minit ;Main Setup Variable (see Appendix) PRINT *[G]desc ;BIF Variable (see Appendix) When a script command is expecting a numeric parameter (a number), if you omit the number (or you specify a variable that is holding a non-numeric value) 0 is assumed unless a specific default value is mentioned in the command DESCRIPTION section. For example if you did this: variable x "here is some text" ;store text in 'x' variable y add y x 10 ;y = x + 10 then the result in 'y' would be 10, since 'x' is not holding a number (0 + 10 = 10). If you truly did want to "add" text to a number or vice versa (make a string longer), you'd use STRCAT: Not ADD. NOTE: Script commands that accept another script command (such as the OFFLINE command demonstrated earlier) provide your scripts with decision- making abilities. All commands that take a command parameter will ONLY execute the command IF a certain condition is true or false. For example: ONLINE cCOMMAND The ONLINE command ONLY executes cCOMMAND (which signifies any other script command) IF the modem is currently offline. The WHEN commmand ONLY executes cCOMMAND if/when specific text is found from the BBS, and so forth. If the condition is false cCOMMAND is not executed, and Icom skips the rest of the script line, and proceeds to the next line of the script. 2.3 ERRORLEVEL Description Listed in each ERRORLEVEL section are the numbers (if any) you can check by accessing the $ERRORLEVEL System Variable, after a script command finishes. If no ERRORLEVEL section exists then the command doesn't modify the $ERRORLEVEL variable. For example, the GETS command gets keyboard input from the user, but you might want to check to see whether the user pressed the [Esc] key, or simply entered nothing. You can test for these conditions by referring to the Detailed Command Summary of the GETS command, and looking at the ERRORLEVEL section: 0 No errors, the user entered something. 1 The user pressed the [Enter] key, but didn't enter anything. 2 The user pressed the [Esc] key or right mouse button. Intellicomm v2.01 SCRIPT.DOC 23 In a script you could test for these conditions by doing something like the following: variable myvariable while 1 ;loop until BREAK gets myvariable 10 ;10 is the max characters the user can enter if $ERRORLEVEL = 0 ;[Esc] not hit, variable not empty print "Thanks for entering: " myvariable break ;exit the WHILE loop else ;variable empty or [Esc] was pressed print "Please enter something, or press [Esc] to cancel." endif endwhile The $ERRORLEVEL variable remains valid only for a short time, until another script command modifies it. Make sure you check for errors immediately after the command in question, before using any other commands, or the value of $ERRORLEVEL may not be valid. If you must check $ERRORLEVEL at some later point, just assign it to your own variable immediately after the command, then check your own variable later: variable MyVariable variable MyErrorlevel GetAgain: gets MyVariable 10 assign MyErrorlevel $ERRORLEVEL ;save the value for later use ;you could not use other script commands which modified ; $ERRORLEVEL ... and later in the script: if MyErrorlevel <> 0 ;not equal to zero? msgwind "Please enter something!" goto GetAgain endif Intellicomm v2.01 SCRIPT.DOC 24 3. DETAILED COMMAND SUMMARY ADD______________________________________________________________________ SUMMARY ADD vSUM nADDEND1 nADDEND2 DESCRIPTION Adds nADDEND1 to nADDEND2 and stores the result in vSUM. If either of the addends is missing (or contain text instead of a number), ADD will assume 0. SEE ALSO ADD, DIV, MUL, SUB EXAMPLE variable result ADD result 5 10 ;stores 5 + 10 (15) in variable 'result' print result ADDSLASH_________________________________________________________________ SUMMARY ADDSLASH vSTRING DESCRIPTION To be used when building filenames, ADDSLASH checks vSTRING to ensure that it has a trailing back slash (\). If not, one is added. Note that if the very last character in vSTRING is a colon (a lone drive letter, such as C:), a slash is not added. SEE ALSO STRIPSLASH EXAMPLE variable customdir "C:\TEMP\" ;default value printnc "Enter directory: " gets customdir 64 ADDSLASH customdir ;add trailing slash if user forgot to add one ALARM____________________________________________________________________ SUMMARY Intellicomm v2.01 SCRIPT.DOC 25 ALARM nTIMES DESCRIPTION Sounds an alarm on the PC speaker nTIMES times. The alarm sounded is the same alarm you hear in manual mode after a connection and a file transfer. The alarm is only sounded if the user has BOTH of these main setup items turned on (both are on the "General" setup screen): | Sound . . . . . . . . . . On | | Pager . . . . . . . . . . On | You can force these items on by modifying the $SOUND and/or $ALARMS System Variables, if necessary. If you do modify the values make sure you save the ORIGINAL values first, and restore them when you're done. See the example below. SEE ALSO TONE, $ALARMS, $SOUND EXAMPLE 1 ALARM 1 ;sound the alarm once EXAMPLE 2 variable old_alarms $alarms ;save original value of $ALARMS variable old_sound $sound ;save original value of $SOUND assign $alarms 1 ;1 = On, 0 = Off assign $sound 1 ;1 = On, 0 = Off ALARM 3 ;this will DEFINITELY be sounded assign $alarms old_alarms ;restore the original values assign $sound old_sound AND______________________________________________________________________ SUMMARY AND vRESULT nNUM nBITMASK DESCRIPTION Performs a bitwise AND on nNUM using nBITMASK, and stores the result in vRESULT. Unless you're a programmer, you probably will never use AND. SEE ALSO OR, SHL, SHR, XOR EXAMPLE variable someflag Intellicomm v2.01 SCRIPT.DOC 26 variable result AND result someflag 1 if result = 0 print "Bit 1 is CLEAR in variable 'someflag'" else print "Bit 1 is SET in variable 'someflag'" endif APPEND___________________________________________________________________ SUMMARY APPEND sSOURCEFILE sTARGETFILE DESCRIPTION Adds the entire contents of file sSOURCEFILE to the end of file sTARGETFILE. If sTARGETFILE exists, Control-Z characters (if any) are stripped from the end of the file before appending sSOURCEFILE. If sTARGETFILE doesn't exist it is created if possible. You may (and should) specify a drive and path in both filenames. If drives/directories are not specified, APPEND assumes the current DOS directory, which could be any drive/directory on the system unless your script issued a CHDIR command recently. NOTE: Neither the source nor the target file should be open (CAPTURE or FOPEN) when APPEND is called. If you want to APPEND to (or from) the currently open CAPTURE file, close it first: CAPPUSH ;save filename, open/closed/paused status CAPCLOSE ;close it APPEND "D:\TEMP\MYDATA.TXT" $CAPTURE_FNAME ... or ... APPEND $CAPTURE_FNAME "D:\TEMP\TMPCAP.CAP" CAPPOP ;restore to previous state If you have previously FOPENed either the sSOURCEFILE or sTARGETFILE, you should also FCLOSE the file before using APPEND on the file(s). But FCLOSE causes the current file pointer position to be lost. If you don't want to lose the position of the file pointer: VARIABLE fpos FTELL fpos myfile ;store file pointer position ;where 'myfile' is the file handle of the open file FCLOSE myfile ;close it APPEND ... ;do your append to or from the file FOPEN myfile ... ;repeat the FOPEN as it was done earlier FSEEK myfile fpos 1 ;seek back to same position ERRORLEVEL 0 Successful. 1 Source file couldn't be opened. Intellicomm v2.01 SCRIPT.DOC 27 2 Target file couldn't be opened. SEE ALSO APPENDS, APPENDSNC, COPY, FOPEN, FPUTS, FPUTSNC, FPUTC, FCLOSE EXAMPLE APPEND "C:\TEMP\MYFILE.TXT" "D:\ANOTHER.TXT" APPENDS__________________________________________________________________ APPENDSNC________________________________________________________________ SUMMARY APPENDS sTARGETFILE sSTRING APPENDSNC sTARGETFILE sSTRING DESCRIPTION APPENDS(tring), adds sSTRING to the file sTARGETFILE (a FILENAME.EXT preferably including a drive and/or directory; D:\PATH\FILENAME.EXT, etc). If sTARGETFILE exists, Control-Z characters are stripped from the end of the file before sSTRING is added. If the file doesn't exist, it is created if possible. sSTRING is followed by a Carriage Return (CR) and Line Feed (LF) to terminate the line in the file when APPENDS is used. APPENDSNC (NC for 'N'o 'C'arriage Return) does the same as APPENDS but doesn't terminate the line with CR/LF. I.e. if you execute multiple APPENDSNC commands, you'll end up with a single line of text in sTARGETFILE. These commands can be used in your scripts to easily keep track of errors/status messages on-disk. The LIST command can then be used to display the errors/messages when your script ends. Or you can use FOPEN and FGETS to get each error/status line out of the file, and you can then test the results to do some "post script" error handling or cleanup. You can also use APPENDS to add new "keywords" to the Tagger's keyword lists (stored in \ICOM\*.KWD files), and you can add notes to BIFs, etc. NOTE 1: When specifying sTARGETFILE, if you omit the drive and path (D:\PATH\), the CURRENT DOS DIRECTORY is assumed which could be any drive and/or directory on the system. Always specify full pathnames (or use a CHDIR command) to ensure that you're dealing with the proper directory. NOTE 2: The FOPEN command is not required prior to using APPENDS/ APPENDSNC, and in fact the file you're appending to should NOT be open (Icom never leaves BIF, Keyword files, etc., open; it loads them into memory when necessary, then closes them). APPENDS/NC automatically calls FOPEN prior to appending, and FCLOSE to close the file after the append. Thus, if you're appending many lines to a text file it would be more efficient to use FOPEN (in append mode), FPUTS or FPUTSNC (several Intellicomm v2.01 SCRIPT.DOC 28 times, if necessary) to add your text, then FCLOSE. This avoids the calls to FOPEN and FCLOSE which APPENDS/APPENDSNC automatically does for each line, and thus allows 'buffering' of the data for more efficient disk writes. ERRORLEVEL (Both commands) 0 Successful. 1 sTARGETFILE couldn't be opened. Either you specified a bad "FILENAME.EXT" (or D:\PATH\FILENAME.EXT ... this command will NOT create directories), or the disk drive door was open, or there were no available DOS 'file handles'; the user can remedy the latter by increasing FILES= in the CONFIG.SYS file. 2 sSTRING couldn't be appended (disk write error). This usually occurs if the disk is full, but could be any number of disk write errors. SEE ALSO APPEND, FOPEN, FPUTSNC, FPUTS, FPUTC, FCLOSE EXAMPLE 1 variable errorfile $HOME_DIR ;put the Icom home dir in 'errorfile' strcat errorfile "ERRORS.!!!" ;add the filename delete errorfile ;start fresh, kill last error file if any ;when errors are encountered in your script... APPENDS errorfile "<X has occurred> error." ;when your script ends: EXIST errorfile LIST errorfile ;if errors occurred, list them EXAMPLE 2 variable filename $HOME_DIR "NOTE.KWD" ;Tagger 'Note File' keywords ;NOTE: You shouldn't modify ANY Icom system files without notifying ; the user (in your script docs) and/or getting permission via keyboard ; input first. APPENDS filename " Note this text " ;add a new keyword to 'Note' assign filename $BIF_DIR ;put the Icom BIF Directory in 'filename' strcat filename $BIF_NAME ;note: the .BIF extension isn't in here strcat filename ".BIF" ; so we must add it ;BIF 'notes' are always at the end of a BIF and use the format: ; <TAB>"One line of note text"<CR><LF> ; ^I (Control-I) is a <TAB> character, and ^" is used to specify ; double quotes within strings (which must also be surrounded by ; double quotes) APPENDS filename "^I^"Add this line of text to the BIF notes.^"" ASSIGN___________________________________________________________________ Intellicomm v2.01 SCRIPT.DOC 29 SUMMARY ASSIGN vVARIABLE snNEWDATA DESCRIPTION Copies sNEWDATA (or nNEWDATA; text or a number) to vVARIABLE. ASSIGN is used when you want to change the contents of an existing variable. The variable vVARIABLE must be defined with the VARIABLE command (or must be a System/Main Setup/BIF Variable) before using ASSIGN. Note that as with all 's'tring-type parameters, you can also use numbers where necessary. Either of these will assign the number 1 to 'myvariable': ASSIGN myvariable "1" ASSIGN myvariable 1 SEE ALSO VARIABLE EXAMPLES variable myvariable ASSIGN myvariable 0 ;myvariable = zero ASSIGN myvariable -1 ;myvariable = minus one ASSIGN myvariable "some text" ;myvariable = "some text" ASSIGN myvariable $DOW ;Store Day of Week in myvariable ASSIGN $DL_PROTOCOL "Z" ;change download protocol to Zmodem ASSIGN $SCRN_COLOR 79 ;change current screen color to ; white on red (see COLOR CODES ; appendix) BEEP_____________________________________________________________________ SUMMARY BEEP DESCRIPTION Sounds a beep on the PC speaker. SEE ALSO TONE EXAMPLE printnc "Roadrunner... " BEEP BEEP Intellicomm v2.01 SCRIPT.DOC 30 print "The coyote's after you." printnc "Roadrunner... " BEEP BEEP print "If he catches you you're through." BOX______________________________________________________________________ SUMMARY BOX sBOXTITLE nX1 nY1 nX2 nY2 DESCRIPTION The parameters, from left to right are: 1. The Box Title (goes in the top border, as you see in Icom boxes). 2. The x1 screen column (left to right) of the top corner. 3. The y1 screen row (top to bottom) of the top corner. 4. The x2 screen column of the bottom corner. 5. The y2 screen row of the bottom corner. Screen coordinates start at 1, 1 (top left corner). A standard text screen (mono or color) is 80 columns wide by 25 rows high (x coordinates range from 1-80, y coordinates range from 1-25). EGA displays can display 42 rows (y coordinates range from 1-42), and VGA displays can display 50 rows (y coordinates range from 1-50). The terminal status line is normally occupying the bottom-most screen line and CAN be overwritten with the BOX command (see the NOTE below). You can check the current number of columns/rows on-screen by accessing the $SCRN_HEIGHT and $SCRN_WIDTH System Variables, if need be. NOTE: The information currently on-screen (if any) is overwritten by the BOX command. If you wish to save the current screen before displaying your BOX and restore the screen after you're done with it, use VPUSH and VPOP before/after the BOX command, or use the WNDOPEN command which does the same thing as BOX but saves the current screen data, color and cursor coordinates. Further, BOX does NOT set the logical screen window (see the WINDOW command) so PRINT, PRINTNC, CLS and GOTOXY do not observe the box limits. Again, use WNDOPEN if this is what you want. SEE ALSO WNDOPEN, $SCRN_HEIGHT, $SCRN_WIDTH EXAMPLE vpush ;save current screen BOX "Box Title" 1 1 $SCRN_WIDTH $SCRN_HEIGHT ;displays a box that covers the whole screen gotoxy 2 2 pause "Press a key and this box is history..." vpop ;restore screen saved with VPUSH Intellicomm v2.01 SCRIPT.DOC 31 BOX "Box Title" 20 10 60 16 ;display a box with top corner at screen column 20, row 10 ; and bottom corner at a screen column 60, row 16 ; The coordinates are where the box border is drawn, so you'd have from ; 21, 11 to 59, 15 to write in, if you wanted to stay in the borders. printraw 23 13 $NORM_COLOR "Here is some text inside the box." ;printraw takes only two screen coordinates; row (x1) and column (y1) ; to start printing the message at. $NORM_COLOR is the proper color ; to use inside boxes (it's the color BOX sets the inside of the ; all boxes to; as defined by the user in the main setup). BOXGETS__________________________________________________________________ SUMMARY BOXGETS vINPUT nMAXLEN [sBOXTITLE] [sHELPLINE] DESCRIPTION Displays a centered box on the screen (adjusted to size according to the parameters specified after BOXGETS) gets user input of no more than nMAXLEN characters, and stores the user input in variable vINPUT. sBOXTITLE (if any) is displayed in the box border and sHELPLINE (if any) is displayed centered inside the box just above the input field. If variable vINPUT contains any data, it is offered to the user as a default response. If you wish to display a Help Line, but DON'T want a Box Title, simply specify "" as the Box Title (e.g. BOXGETS myvar 10 "" "Help Line"). The box and user input line use the same colors that Icom uses on its own boxes/menus, etc., as defined by the user in the Icom main setup. Output from the BOXGETS command looks like this (with graphics characters instead of text) with a 'Help Line': +=| Box Title |====================================================+ | | | This is the Help Line where you can give the user instructions | | | | ><User input here> | | | +==================================================================+ It looks like this if no Help Line is specified (size adjusted according to the 'len' parameter: +=| Box Title |========+ | | | ><User input here> | | | +======================+ The contents of the screen that the box overwrites is saved prior to Intellicomm v2.01 SCRIPT.DOC 32 displaying the box and restored when the user presses [Enter] or the left mouse button, [Esc] or the right mouse button, or presses a key that matches a $HOTKEY_? variable (see the example). When the box is on the screen, the user can type text (or numbers, symbols, etc.) on the input line to the maximum length specified by the 'len' parameter, and can use any of the following editing keys: [Left] Moves the cursor one position to the left (if possible). [Right] Moves the cursor one position to the right (if possible). [Home] Moves the cursor to the first character on the input line. [End] Moves the cursor to the the position after the last character on the input line. [Ctrl-Left] Moves the cursor to the beginning of the previous word. [Ctrl-Right] Moves the cursor to the beginning of the next word. [Ctrl-End] Deletes all characters from the cursor to the end of the input line. [Ins] Toggles insert/typeover mode (insert/typeover mode is saved from one BOXGETS/GETS to the next). [Del] Deletes the character under (at) the cursor pulling characters from the right (if any) to the cursor position. [Backspace] Deletes the character to the left of the cursor, moves the cursor left one position, pulling characters to the right (if any) along with it. [Enter] Ends BOXGETS, restores the screen (see ERRORLEVEL below). [Esc] Ends BOXGETS, restores the screen (see ERRORLEVEL below). The mouse can also be used to move the cursor by moving it left/right, and pressing the Left mouse button is equivalent to pressing the [Enter] key while pressing the Right mouse button is equivalent to pressing the [Esc] key. As well, while the user is entering text in the box, certain 'hotkeys' remain active for convenience. The hotkeys available are: [Alt-A] Call Editor (internal or external as defined in main setup). [Alt-J] Jump to DOS shell. [Alt-N] User-defined Hotkey 1 (defined in main setup). [Alt-O] User-defined Hotkey 2 "" "" [Alt-V] Call Archiver (as defined in main setup). If the user presses any of these hotkeys while entering text in the edit box, control is temporarily turned over to the task the user selected. When the user exits the called task control returns to the edit box with everything exactly as it was before the hotkey was pressed. The same applies to the GETS/GETSXY (BOXGETS without the box) commands. NOTE 1: Offering default responses (by placing the default in variable 'var' before calling BOXGETS) is a handy feature, but won't be practical in all cases. Where default responses are not possible, make sure that you CLEAR your variable before calling BOXGETS (ASSIGN myvariable "" clears a variable). See the EXAMPLE for more information. NOTE 2: If a default is offered, the user can edit it using the cursor Intellicomm v2.01 SCRIPT.DOC 33 keys mentioned above. However, if the user presses a NON-editing key (a letter, number, etc) as the first character, the default response is cleared automatically. It's assumed that the user didn't want the default if anything but an editing key is pressed as the first key. ERRORLEVEL 0 The user entered something (variable vINPUT contains data) then pressed the [Enter] key or left mouse button. 1 The user pressed [Enter], but variable vINPUT is empty ... nothing was entered. 2 The user pressed the [Esc] key or right mouse button to cancel. If this occurs, the contents of variable vINPUT reverts to its original value whether the user changed it on the input line or not. 256+ If a value of 256 or greater is in $ERRORLEVEL when BOXGETS returns, the user pressed a key defined in one of the $HOTKEY_? variables. See the example for details. SEE ALSO GETS, GETSXY, INKEY EXAMPLE 1 variable myvariable 5 ;define 'myvariable', assign 5 as a default. BOXGETS myvariable 3 "Capturing Bulletin" "Enter bulletin to capture" ;a box would be displayed as outlined above, and on the 'User Input' ; line, 5 would be offered as a default bulletin number. ;if $ERRORLEVEL is equal to 0, the user entered something, so we ; execute the subroutine 'cap_bulletin'. if $ERRORLEVEL = 0 gosub cap_bulletin assign myvariable "" ;clear the contents of 'myvariable' (no default). BOXGETS myvariable 64 "Box Title" "Help Line" ;example of no default return ;exit the script cap_bulletin: send "B " myvariable " NS" ;send PCBoard [B]ulletin command waitfor "Command? " 120 ;wait 2 minutes to return to menu prompt. return ;return from subroutine EXAMPLE 2 ($HOTKEY_? USAGE -- ADVANCED) variable s assign s "SOMEFILE.EXT" ;a default value for BOXGETS assign $HOTKEY_1 8448 ;Assign [Alt-F] to $HOTKEY_1 for BOXGETS ; If the user presses [Alt-F] while entering ; text, BOXGETS will set $ERRORLEVEL to 8448 ; (the value of the key pressed). BOXGETS s 64 "Upload" "Enter filename or press [Alt-F] for File Picker" Intellicomm v2.01 SCRIPT.DOC 34 assign $HOTKEY_1 0 ;clear the hotkey switch $ERRORLEVEL case 0 ;regular text was entered upload $UL_PROTOCOL s endcase case 1 ;'s' is empty or [Esc] was pressed case 2 endcase case 8448 ;[Alt-F] was pressed variable lstname $HOME_DIR "GETFNAME.LST" ;C:\ICOM\GETFNAME.LST stritem s $UL_PATH 1 ;store 1st dir on U/L PATH in s getfname s "Upload" "Please ^"Select^" one or more files to upload" notexist lstname goto skip_ul strins lstname "@" 0 1 ;@C:\ICOM\GETFNAME.LST upload "Z" lstname ;uploads all files on the list ;Confused? See the GETFNAME detailed summary endcase endswitch ;Note that the above can be accomplished with a simple UPLOAD command. ; If you don't specify a filename after UPLOAD, basically the same ; process as the above is carried out by UPLOAD. CADDREC__________________________________________________________________ SUMMARY CADDREC DESCRIPTION CatalogADDRECord adds a new record to the currently open Tagger catalog (see COPEN). The contents of the new record will be the current contents of the various Tagger record fields (explained in SCRTUTOR.DOC). See the example for details. NOTE: The $CCDATE_FLD (Catalog Date field) is automatically set to 'today' by CADDREC. ERRORLEVEL 0 = Record successfully added. 1 = Unable to add record (disk write error, etc). SEE ALSO CPUTREC EXAMPLE notexist "C:\TEST\SOMEFILE.ZIP" exit ;some file you wish to import ;NOTEXIST (as well as EXIST,FINDFIRST,FINDNEXT) sets various System Intellicomm v2.01 SCRIPT.DOC 35 ; Variables which provide information about the file that was found. ; See FINDFIRST for details. We're only interested in $FDATE here ; (the date of the file) copen "FILELIST" cclearbuf ;clear all the fields assign $CNAME_FLD "SOMEFILE.ZIP" date2cdate $CFDATE_FLD $FDATE ;file date to dBASE format ;if you want to tag the file for upload you must either do it after ; the new record has been added (with CTAGREC) or you must be sure ; to include the "Upload Pending> BIFID1;BIFID2" line to the end of ; the file description, to tell Icom where to upload the file. A ; simple tag isn't good enough when dealing with the FILELIST (upload) ; catalog assign $CTAG_STAT "T" ;tagged cputdesc "This is a description of SOMEFILE.ZIP. It might continue on" cputdesc "for several lines... See CPUTDESC for details." cputdesc "Upload Pending^P JOESBBS" ;Note that ^P (Ctrl-P) is the proper character to use after Upload ; Pending and Uploaded To. This is the hard way to tag a file and ; it should only be attempted when adding new records with CADDREC ; (if even then). Read on for an easier way. ;Once you get all the fields (in memory) set up the way you want them, ; go ahead and call CADDREC to add the new data to the catalog. CADDREC if $ERRORLEVEL = 0 ;was CADDREC successful? variable RecordNumber ;Yes ctell RecordNumber ;what record # did we add? print "Record #" RecordNumber " added to FILELIST catalog." ;you could perform 'CTAGREC RecordNumber "JOESBBS"' here and ; achieve the same effect as the (more difficult) tag above. else print "Unable to add record to FILELIST." endif cclose CAPCLOSE_________________________________________________________________ SUMMARY CAPCLOSE DESCRIPTION Closes the current capture file, if open (no harm is done if the capture file was already closed). To PAUSE the capture file without closing it, Intellicomm v2.01 SCRIPT.DOC 36 use the CAPPAUSE command. SEE ALSO CAPTURE, CAPPAUSE, $CAP_NAME, $CAP_STAT EXAMPLE dial "A BBS" ;capture is normally opened automatically on connect CAPCLOSE ;...use CAPCLOSE to close it if you like. CAPPAUSE_________________________________________________________________ SUMMARY CAPPAUSE DESCRIPTION Toggles the pause status of the capture file (if open). If the capture file is currently unpaused (capturing), then CAPPAUSE pauses it. If paused, CAPPAUSE unpauses it. While paused, nothing received from the BBS, or printed with PRINT, PRINTNC or PAUSE is written in the file. You can check the current state of the capture file by accessing the $CAP_STAT System Variable. SEE ALSO CAPPUSH, CAPPOP, CAPTURE, CAPCLOSE, $CAP_NAME, CAP_STAT EXAMPLE cappush if $CAP_STAT = 1 CAPPAUSE ;pause if open print "This portion of the online session will not be captured." send "CHAT" chat cappop ;restore the previous state (open/closed/paused) CAPSTAMP_________________________________________________________________ SUMMARY CAPSTAMP DESCRIPTION Stamps the same type of header that Icom itself stamps: ==<< YY-MM-DD HH:MM:SS BIFID - BBS Name >>============================ Intellicomm v2.01 SCRIPT.DOC 37 in the current capture file (if open) and if *capstamp (the main setup option 'Stamp Date/Time Cap Open' is on. ERRORLEVEL SEE ALSO EXAMPLE variable old_stamp *capstamp capture "NEWCAP.CAP" assign *capstamp 1 ;to make sure it gets stamped, whether the user ; has this option turned on or not CAPSTAMP assign *capstamp old_stamp CAPPUSH__________________________________________________________________ CAPPOP___________________________________________________________________ SUMMARY CAPPUSH CAPPOP DESCRIPTION CAPPUSH saves the current $CAP_NAME (capture filename D:\PATH\FILENAME.EXT) and $CAP_STAT (open/closed/paused status) to an internal buffer. CAPPOP restores the capture filename/status saved with the last CAPPUSH (multiple times, if necessary). Every time you call CAPPUSH, you overwrite the previously saved values. I.e. no "stack" is available to save multiple capture filenames. You're free to implement your own form of CAPPUSH if you must save multiple capture filenames in your scripts: variable capname1 $CAPTURE_NAME variable capstat1 $CAPTURE_STAT ...later variable capname2 $CAPTURE_NAME variable capstat2 $CAPTURE_STAT ...restore as needed assign $CAPTURE_NAME capname2 assign $CAPTURE_STAT capstat2 ...etc. SEE ALSO CAPCLOSE, CAPPAUSE, CAPTURE, $CAP_NAME, $CAP_STAT EXAMPLE Intellicomm v2.01 SCRIPT.DOC 38 CAPPUSH ;save old capture filename/status capture "\TEMP\TEMP.CAP" ;open a new capture file send "B 15 NS" ;PCBoard, show bulletin #15 in non-stop mode waitfor "Command? " ;wait for BBS main menu CAPPOP ;restore the original capture filename/state CAPTURE__________________________________________________________________ SUMMARY CAPTURE [sCAPFILE ...] DESCRIPTION CAPTURE closes the current capture file (if open), then opens a new capture file. sCAPFILE may contain the full D:\PATH\FILENAME.EXT (drive, path, filename, extension) of the new capture file. If you omit D:\PATH\ or .EXT, the D:\PATH\ and/or .EXT is taken from the current contents of $CAP_NAME (the last capture file opened, or the default capture filename as defined in the Icom main setup). Note that CAPTURE accepts multiple parameters, and the purpose of this is to allow you to build filenames based on the contents of variables: variable mycapdrive "D:" variable mycapdir "\TEMP\CAP\" variable mycapfname "TEMP.CAP" CAPTURE mycapdrive mycapdir mycapfname The above is the same as CAPTURE "D:\TEMP\CAP\TEMP.CAP". If the sCAPFILE parameter is omitted (or is a blank) and the capture file is currently closed, CAPTURE prompts the user for a new capture filename. If the capture file is currently open, the Close/Pause menu is displayed (same as pressing [Alt-L] from Terminal Mode). Thus, you can use CAPTURE to interact with the user as well, possibly to prompt for a custom capture filename. When a capture is open, Icom appends each line sent from the BBS *and* any data your script displays with the PRINT, PRINTNC or PAUSE commands, to the end of the capture file. CAPTURE always adds to the end of files if they exist; it never overwrites files. If you wish to start a new capture file, simply use a DELETE, RENAME, or RENUMBER command prior to calling CAPTURE. You can later view the capture file to review the BBS session, using either an external text file viewer, or Icom's built-in File Viewer (also see the LIST command; you can also have your script display capture files via the File Viewer). See the EXAMPLE below for useful capture techniques. NOTE 1: The "Stamp Date/Time Cap Open" item on the Icom main setup General Settings screen controls whether the CAPTURE command stamps Intellicomm v2.01 SCRIPT.DOC 39 newly opened capture files with a line similar to this: ==<< YY-MM-DD HH:MM:SS BIFNAME - BBS Description >>==================== These lines can be useful in processing capture files after an online session (either by eye or with the script file I/O commands), since they give you both the date/time of the connection (always in the format YY- MM-DD HH:MM:SS [Year-Month-Day Hour:Minute:Second]), and the BIF ID. However, there may be times when you want to disable this capture stamping. If the need arises you can do so by modifying the *capstamp Main Setup Variable: variable old_capstamp *capstamp ;save old value assign *capstamp 0 ;0 = Off CAPTURE "SOMEFILE.CAP" ;won't stamp date/time line on open assign *capstamp old_capstamp ;restore previous value NOTE 2: As mentioned earlier, if you omit the drive, path, or extension when specifying the sCAPFILE parameter, CAPTURE simply "fills in" the portion you DO specify. For example, if you did this: CAPTURE "C:\ICOM\LST\MYLIST.NEW" CAPTURE "ICOM" then the second CAPTURE command would capture to C:\ICOM\LST\ICOM.NEW. Only a filename was specified in the second CAPTURE command, so that's all CAPTURE replaces. This can be useful in many cases ... and can produce unexpected results in other cases if you don't keep it in mind. To ensure that you're capturing to the exact drive/directory/filename/ extension you want, make sure you SPECIFY them in the CAPTURE command. ERRORLEVEL 0 Successful capture open. 1 Unable to open capture file (bad filename, disk full, or no file handles). A status window (MSGWIND) will be displayed by CAPTURE automatically if the open fails, to notify the user. So there's no need to display an error message in the script, but you might want to abort a specific task, such as sending a command to the BBS to display a long list of files, etc., if you get an error opening the file. Note also that if a disk write error occurs while Icom is updating (adding to) the capture file, an error is displayed to the user and the capture file is automatically closed. SEE ALSO CAPCLOSE, CAPPAUSE, DELETE, RENAME, RENUMBER, $CAP_NAME, $CAP_STAT EXAMPLE variable key CAPPUSH ;save current capture filename/status Intellicomm v2.01 SCRIPT.DOC 40 CAPTURE "\TEMP\BLT5.CAP" ;close curent cap, open a new capture file send "B 5 NS" ;PCBoard read bulletin 5, non-stop waitfor "Command?" 120 msgopen "Capturing bulletin 1 to printer; ready printer and press a key" inkeyw key ;pause for a keystroke or mouse click msgclose ;close the message window send "B 1 NS" ;Tell the BBS to display bulletin 1, non-stop CAPTURE $PRN ;start capturing to the printer waitfor "Command?" 120 CAPPOP ;restore the original capture filename and state CCLEARBUF________________________________________________________________ SUMMARY CCLEARBUF DESCRIPTION Clears $CCDATE_FLD, $CDAY_FLD, $CFDATE_FLD, $CFLAG_FLD, $CLOC_FLD, $CNAME_FLD, $CPRIORITY_FLD, $CSIZE_FLD, $CTAG_FLD, and the file (record) description buffer. Use CCLEARBUF to clear the entire record buffer before you ASSIGN various items to various fields and CADDREC (add a new record to the catalog). Note that CCLEARBUF doesn't clear any records on-disk. It only clears the catalog record buffer (where records are loaded from disk when you perform a CGETREC). SEE ALSO CCLEARDESC EXAMPLE copen "NEWFILES" CCLEARDESC assign $NAME_FLD "SOMEFILE.EXT" assign $CLOC_FLD "BIFID" caddrec cclose CCLEARDESC_______________________________________________________________ SUMMARY CCLEARDESC DESCRIPTION Clears the catalog description buffer (memory only). The description buffer is located in memory and it is where file descriptions are loaded when you perform a CGETREC. CGETDESC / CPUTDESC then allow you to Intellicomm v2.01 SCRIPT.DOC 41 access this memory buffer. Use CCLEARDESC to quickly clear out the description buffer, when you want to CPUTDESC an entirely new description in the buffer (such as clearing the description before using the FILE_ID.DIZ description). SEE ALSO CCLEARBUF EXAMPLE copen "NEWFILES" cgetrec CCLEARDESC cputdesc "This is a new description." cputrec cclose CCLOSE___________________________________________________________________ SUMMARY CCLOSE DESCRIPTION Closes the currently open Tagger catalog (see COPEN). CCLOSE is called automatically when your script ends, if you forget to call it yourself. But you should get into the habit of doing it yourself in case it becomes necessary to remove this auto-CCLOSE protection in the future. SEE ALSO COPEN EXAMPLE ;See SCRTUTOR.DOC for real examples COPEN "NEWFILES" CCLOSE CDATE2DATE_______________________________________________________________ SUMMARY CDATE2DATE vDATE sCDATE DESCRIPTION Converts a Catalog/dBASE date to the date format the user has set up in the Icom main setup. Catalog dates are stored in the format YYYYMMDD (YearMonthDay), which is great for sorting an indexing... but not so Intellicomm v2.01 SCRIPT.DOC 42 great for human consumption. Use CDATE2DATE to easily convert Catalog dates ($VIEW_DATE, $CCDATE_FLD, $CFDATE_FLD) to a more eye-pleasing format. SEE ALSO DATE2CDATE EXAMPLE variable vdate variable fdate variable cdate copen "NEWFILES" CDATE2DATE vdate $VIEW_DATE ;current View Date of catalog cgetrec ;grab a record (any one will do) CDATE2DATE fdate $CFDATE_FLD ;File Date CDATE2DATE cdate $CCDATE_FLD ;Catalog Date print "NEWFILES Catalog. Current View Date: " vdate print "Filename : " $CNAME_FLD print "File Size : " $CSIZE_FLD print "File Date : " fdate print "Catalog Date: " cdate cclose CDATEDIFF________________________________________________________________ SUMMARY CDATEDIFF vDIFFERENCE sCDATE1 sCDATE2 DESCRIPTION Subtracts sCDATE2 from sCDATE1 and stores the difference (in days) in vDIFFERENCE. Both sCDATE1 and sCDATE2 must contain valid dates in Tagger catalog (dBASE) format: YYYYMMDD. NOTE: If sCDATE1 is more recent than sCDATE2, you'll get a negative number in vDIFFERENCE. sCDATE2 is subtracted FROM sCDATE1, so sCDATE2 should be the same as, or more recent than, sCDATE1. You'll almost always use this to compare a record's Catalog Date ($CCDATE_FLD) or File Date ($CFDATE) with today's date ($DATE) ... and since you know that a Catalog Date can never be more recent than today's date, it's a simple matter to use today's date as the second date parameter. A file date is another story, and many BBS operators do post files with dates well into the future (01-01-95, etc), to keep the file from being purged from the listings. You can handle that problem as well. See the example for details. SEE ALSO Intellicomm v2.01 SCRIPT.DOC 43 DATE2CDATE EXAMPLE variable diff variable today ;first, we must convert today's date to dBASE format before it'll be ; accepted by CDATEDIFF date2cdate today $DATE copen "NEWFILES" cgetrec ;get a record ;While IF isn't smart enough to do a real date comparison, it works in ; this case since the dates are stored in the format YYYYMMDD. ; ASCII-wise, 0 is 'less than' 9, so if the current record has a year ; that is 'greater than' the current year, or a month 'greater than' ; the current month, or a day 'greater than' today ... we'll know that ; its date is more recent than today (in which case CDATEDIFF is ; invalid since we're comparing to 'today' in the example). This ONLY ; works in this one case, with the dates stored in the format YYYYMMDD. ; See the IF summary for details on string comparisons (these dates are ; just strings of ASCII characters to IF). print "Filename: " $CNAME_FLD if $CFDATE_FLD > today ;the File Date is greater than today's date? assign diff 0 else cdatediff diff $CFDATE_FLD today endif print "File Age: " diff " day(s) old" cdatediff diff $CCDATE_FLD today print "Imported: " diff " day(s) ago" cclose CDELREC__________________________________________________________________ SUMMARY CDELREC nRECNUMBER DESCRIPTION Toggles the deleted status of record nRECNUMBER in the currently open Tagger catalog (see COPEN). With most other record-oriented commands the nRECNUMBER parameter is optional. But it's mandatory with CDELREC so that you're always deleting precisely the record you had in mind. Intellicomm v2.01 SCRIPT.DOC 44 ERRORLEVEL 0 Deleted status successfully toggled. 1 Invalid nRECNUMBER or disk write error. EXAMPLE variable record copen "NEWFILES" csetsort -1 ;-1 = Unsorted (CGETREC ignores $VIEW_DATE) ;delete any records with a Catalog Date ($CCDATE_FLD) older than ; the View Date ($VIEW_DATE). while 1 cgetrec if $errorlevel <> 0 break ;end of catalog if $CREC_STAT = "D" continue ;already deleted, skip it ;Note that using the IF command to compare dates is only valid when ; both dates are in the format YYYYMMDD, as is the case with ; $CCDATE_FLD and $VIEW_DATE. You could not use $DATE and get ; a valid comparison, since $DATE does not use the format YYYYMMDD ; (though you can convert it to YYYYMMDD with a call to DATE2CDATE). if $CCDATE_FLD < $VIEW_DATE ;older than View Date? ctell record ;get the current record number for CDELREC CDELREC record endif endwhile ;you'd have to call CPACK here to actually remove the deleted records cclose CEDITREC_________________________________________________________________ SUMMARY CEDITREC [nRECNUMBER] DESCRIPTION Enters Tagger "Edit Mode", displaying either the current record (if nRECNUMBER is omitted) or record number nRECNUMBER. The user can then edit the record, and press [PgUp] / [PgDn] to move to the next/previous records according to the current sort order (set with CSETSORT). CEDITREC does not return until the user presses [Esc] to exit Edit Mode. EXAMPLE Intellicomm v2.01 SCRIPT.DOC 45 COPEN "NEWFILES" CSETSORT 1 ;Tag Status/Location, forward CEDITREC ;Enter edit mode (top of catalog) CCLOSE CEMPTY___________________________________________________________________ SUMMARY CEMPTY cCOMMAND DESCRIPTION Checks the currently open Tagger catalog (see COPEN) and executes cCOMMAND if it is empty (no valid file records except the header record). If the catalog is NOT empty, cCOMMAND is skipped. EXAMPLE copen "NEWFILES" CEMPTY goto done while 1 cgetrec if $errorlevel <> 0 break print $CNAME_FLD endwhile done: cclose CEXPORT__________________________________________________________________ SUMMARY CEXPORT [sBIFNAME] [sTEXTFILE] [nEXPORTTYPE] [nNODISPLAY] DESCRIPTION Same as selecting "Tools|Export to Text File" from within the File Tagger. CEXPORT exports all visible records (according to the View Date) in sBIFNAME format (according to the positions on the BIF "Bank/List" screen) to text file sTEXTFILE. The records are written to sTEXTFILE in the current sort order (see CSETSORT). If sTEXTFILE exists, it is appended to. Otherwise, it is created. If either sBIFNAME or sTEXTFILE is omitted, the user is prompted for the information, as in the File Tagger. nEXPORTTYPE is an optional number from 1 to 5, which controls the TYPE of files that are exported: 1 = All files (Noted, Tagged and Untagged). 2 = Tagged files only. 3 = Noted files only. Intellicomm v2.01 SCRIPT.DOC 46 4 = Tagged or Noted files only. 5 = Untagged files only. Again, if nEXPORTTYPE is omitted (or 0), the user is prompted for the type of files to export. nDISPLAY controls whether the export routines display any information to the screen. If nNODISPLAY is 0 (zero) or is omitted, CEXPORTREC displays a message to the user while the export takes place. If you want to hide this message, nNODISPLAY can be specified as a non-zero value. ERRORLEVEL 0 Export successful. 1 Catalog empty (nothing exported). 2 sBIFNAME was omitted, CEXPORT prompted for a BIF format, and the user pressed [Esc]. 3 Unable to get the BIF "Bank/List" information from sBIFNAME (sBIFNAME doesn't exist, disk read error, BIF damaged, etc). 4 sTEXTFILE was omitted, CEXPORT prompted for a text file to export to, and the user pressed [Esc]. OR nEXPORTTYPE was omitted, CEXPORT prompted for the type of files to export, and the user selected "Cancel" or pressed [Escl. 5 Unable to open sTEXTFILE. Most likely the filename was invalid (CEXPORT does not create directories), but could also be a disk write error or a lack of DOS file handles. The user can remedy the latter by increasing FILES= in the CONFIG.SYS file. 6 User abort ([Esc] key pressed before export complete). 7 Disk read error. Error reading catalog (disk read error, catalog damaged, etc). 8 Disk write error. Error writing to sTEXTFILE (disk full, various other disk errors). SEE ALSO CIMPORT EXAMPLE COPEN "NEWFILES" date2cdate $VIEW_DATE $DATE ;View Date = today csetsort 3 ;Sort by Filename/File Date ;export all records that were imported today (if any), sorted ; by filename/file date CEXPORT PCB150 "C:\TEMP\ALLFILES.TXT" 1 ;1 = Export all files ;export any TAGGED records, sorted by Location (BBS the file is Tagged ; for). The View Date is ignored on Tagged files so it's not necessary ; to reset the View Date. Anything Tagged will be exported. Intellicomm v2.01 SCRIPT.DOC 47 csetsort 1 ;Sort by Tag Status/Location CEXPORT PCB150 "C:\TEMP\TAGGED.TXT" 2 ;2 = Export Tagged files cclose CFLUSH___________________________________________________________________ SUMMARY CFLUSH DESCRIPTION Writes any data in the catalog buffers of the currently open catalog (see COPEN) to disk. Disk input/output is 'buffered' when reading from/writing to Tagger catalogs (CADDREC, CGETREC, CPUTREC) meaning that memory buffers are used to group disk reads/writes together for more effecient transfers. CFLUSH immediately writes any data in the write buffers to disk, and clears the contents of the buffers. Note that CFLUSH is called automatically when you CCLOSE a catalog, and it normally will not be needed. If power outages are frequent in your area, or if you have just completed some critical script operations on a catalog and you want to ensure that the changes are written to disk immediately, you'll want to use CFLUSH. Otherwise you should let the memory buffers do their work, and just CCLOSE the catalog (which performs a CFLUSH automatically) when you're finished with it. EXAMPLE copen "NEWFILES" ceditrec CFLUSH CFORMATDESC______________________________________________________________ SUMMARY CFORMATDESC nWIDTH DESCRIPTION After calling CGETREC (get a Tagger catalog record), all file descriptions are formatted to a maximum length of 45 characters per line automatically. CFORMATDESC re-formats a record's file description to a new line length of nWIDTH characters maximum. SEE ALSO CGETDESC, CPUTDESC EXAMPLE variable line Intellicomm v2.01 SCRIPT.DOC 48 copen "NEWFILES" while 1 cgetrec if $ERRORLEVEL <> 0 break CFORMATDESC 65 ;65 characters per line cgetdesc line 1 ;get line 1 (will be 65 characters or less) print $CNAME_FLD "^I" line ;^I is a TAB character endwhile cclose CGETC____________________________________________________________________ SUMMARY CGETC vCHAR [nTIMEOUT] DESCRIPTION Gets a single character from the receive buffer and stores it in variable vCHAR. If nTIMEOUT is specified and no characters are received by nTIMEOUT (specified in tenths of a second), CGETC ends and vCHAR will be empty. If nTIMEOUT is omitted, CGETC waits for a character indefinitely. Note that CGETC doesn't deal directly with the COM port. Only Icom's interrupt handler deals directly with the port, and the interrupt handler is driven (called) by hardware interrupts generated by the COM port itself. If/when a character is received, the port sends an interrupt to the processor, and the processor (if it has time) turns control over to Icom's interrupt handler which then grabs the character and stores it in the receive buffer. CGETC simply checks Icom's "Receive Buffer" (size is configurable on the main setup/Terminal screen; it defaults to 4 Kbytes) to see if the interrupt handler stored any characters there. What this means is that whether you call CGETC in your script or not, characters are still being taken from the COM port and stored in the Receive Buffer (until the buffer is about three quarters full, at which time the interrupt handler will activate Flow Control to pause the modems). It works in the background, and is driven completely by the hardware itself ... and it's independant of both Intellicomm's terminal and scripts. So if any characters are "lost", it's because your computer's processor (the hardware) couldn't turn control over to Icom's interrupt handler fast enough. It has nothing to do with your lack of calling CGETC, or the speed at which CGETC is actually called. And the only way to remedy the situation is either to get a faster processor, or to slow the COM port (baud rate) down. Further, there are certain commands you must avoid using, if you intend to use CGETC. One TERMINAL command in your script can do the equivalent of many CGETC's and display the received character(s) on the screen (i.e. any characters in the Receive Buffer are "eaten" by TERMINAL commands, and your script, using CGETC, will never even know they were there). So unless you want Icom's terminal to steal characters before Intellicomm v2.01 SCRIPT.DOC 49 CGETC even sees them, don't call TERMINAL in and around your CGETC's. This use of CGETC, for example, would get every other character received (at best): variable c while 1 CGETC c 10 printnc c terminal ;TERMINAL does its own CGETC/printnc endwhile TERMINAL doesn't do just one CGETC, it does the equivalent of this: while $RXCNT > 0 ;$RXCNT is the number of chars in the Receive Buffer CGETC c printnc c inkey c ;it also checks for and processes keystrokes endwhile I.e. *all* characters waiting in the receive buffer are handle by one single TERMINAL command. Further, the following script commands call TERMINAL on their own: DELAY (use DELAYNC instead; it does not call TERMINAL) SEND (and its variations SENDNC/SENDNCP/SENDNP) SENDBIF WAITFOR So, you don't want to do this either (though you probably wouln't want to anyway): variable c while 1 if $RXCNT > 0 CGETC c sendnc c ;SENDNC calls TERMINAL, so CGETC is useless endif endwhile ERRORLEVEL 0 Character received and stored in vCHAR. 1 nTIMEOUT elapsed and no character was received. Variable vCHAR will be empty in this case. SEE ALSO CGETS, RXBUF, TERMINAL EXAMPLE variable c Intellicomm v2.01 SCRIPT.DOC 50 CGETC c 100 ;wait 10 seconds maximum, then abort if $ERRORLEVEL > 0 print "Timeout." ;one way to check... if c = "" print "Timeout." ;another way to check ;If you don't use a timeout, you should make sure something is ; waiting in the receive buffer before you call CGETC if $RXCNT > 0 CGETC c ;variable 'c' will definitely have a character if $RXCNT is ; greater than (>) zero and there's no need to check $ERRORLEVEL. CGETDESC_________________________________________________________________ SUMMARY CGETDESC vLINEBUF nLINENUM DESCRIPTION Gets description line number nLINENUM from the current Tagger catalog record (see below) and stores it in variable vLINEBUF. Before using CGETDESC you must COPEN a Tagger catalog, and call CGETREC to get a record. CGETDESC is only valid after a call to CGETREC. File description lines are formatted to a maximum of 45 characters per line by CGETREC. Thus CGETDESC gets 45 characters of the description maximum, by default. To change this line length, you can call CFORMATDESC after CGETREC. ERRORLEVEL 0 Description line number nLINENUM was successfully loaded into vLINEBUF. 1 There was no description line numbered nLINENUM (you've reached the end of the description, or it was empty to begin with). SEE ALSO CFORMATDESC, CGETREC EXAMPLE This example demonstrates the entry of a file description to a BBS, during an upload. Such a script could be plugged in to the "Description (@SCRIPTNAME)" item on the BIF "File" screen. When this is the case, Intellicomm will already have the catalog open and will already have obtained the next tagged record (CGETREC), and will already have found the BBS "Enter Description" prompt. Thus, all the script has to do is enter the description to the BBS. Using the example below, you could make modifications (add a couple of WAITFORs or the like) to handle any curves a BBS developer can dream up. Intellicomm v2.01 SCRIPT.DOC 51 variable linenum 1 variable linedat CGETDESC linedat 1 ;get line 1 strblank linedat goto no_descrip ;if blank, goto no_descrip while 1 ;endless loop (until BREAK) CGETDESC linedat linenum if $errorlevel = 1 break ;no more description lines delay 10 ;pause for a second (let BBS catch up) send linedat if linenum >= *[F]flmx break ;Max Lines (BIF "File" screen) inc linenum ;INCrement (linenum = linenum + 1) endwhile if *[F]flmx > 1 send "" ;If more than 1 line permitted, send ; [Enter] on a blank line return no_descrip: send "No description was available for this file." return CGETREC__________________________________________________________________ SUMMARY CGETREC [nRECNUM] DESCRIPTION Loads either the current record (CTELL) or record number nRECNUM from the currently open catalog. Please see INTRODUCTION TO DATABASE COMMANDS in file SCRTUTOR.DOC (included with Intellicomm) for detailed information. ERRORLEVEL 0 = Record successfully loaded. 1 = Unable to load record (end of catalog or nRECNUM is an invalid record number). SEE ALSO COPEN, CCLOSE EXAMPLE copen "NEWFILES" while 1 CGETREC if $ERRORLEVEL > 0 break ;end of catalog endwhile Intellicomm v2.01 SCRIPT.DOC 52 CGETS____________________________________________________________________ SUMMARY CGETS vLINEBUF [nMAXCHARS] [sENDCHAR] [nTIMEOUT] DESCRIPTION Gets a line of input from the current COM port ($COM_PORT) and stores it in variable vLINEBUF. Input is terminated when any of the following occurs: 1. nMAXCHARS number of characters have been received. 150 characters (the maximum allowed) is assumed if nMAXCHARS is zero or is omitted. 2. Either a Carriage Return or character sENDCHAR is received. Note that neither a Carriage Return nor sENDCHAR is stored in vLINEBUF, if received. 3. nTIMEOUT tenths of a second have elapsed (only if nTIMEOUT is specified). CGETS uses the equivalent of CGETC to get each character from the COM port. Please see CGETC for more detailed information. ERRORLEVEL 0 vLINEBUF contains one or more characters, and nTIMEOUT did not lapse. 1 vLINEBUF is empty. Either nTIMEOUT elapsed before a character was received, or nENDCHAR was the first character received. 2 nTIMEOUT was specified, and the timeout period elapsed before a Carriage Return or nENDCHAR was received, or before nMAXCHARS were received. SEE ALSO CGETC EXAMPLE variable UserName sendnc "Please enter your name: " CGETS UserName 50 "^M" 60 send "^M^JWelcome, " UserName "." CHAT_____________________________________________________________________ SUMMARY CHAT DESCRIPTION Intellicomm v2.01 SCRIPT.DOC 53 Enters chat mode (same as pressing [Alt-T] from Terminal mode). This command does not return until the users presses [Esc] to exit chat mode. EXAMPLE print "Entering chat mode..." CHAT CHECKVERSION_____________________________________________________________ SUMMARY CHECKVERSION sMINIMUMVERSION DESCRIPTION CHECKVERSION is meant to be used as the first command in a script that is distributed to the general public. It checks the current Intellicomm version number, and aborts the script with the following message if the version of Intellicomm executing the script is lower than sMINIMUMVERSION: Sorry, this script requires Intellicomm sMINIMUMVERSION or above. (where sMINIMUMVERSION is the version you specify). sMINIMUMVERSION can specify the major version number only ("2") or the major version and the first decimal ("2.0") or the full version number ("2.00"). Only the portion you specify in sMINIMUMVERSION is checked. NOTE: CHECKVERSION will not be very useful until Intellicomm v1.00 is no longer in use, since Icom v1.00 did not support the CHECKVERSION command at thus if your v2.0x script is executed under Icom v1.00, Icom v1.00 will simply ignore the command and continue to execute the script anyway. Further, until new script commands/variables/concepts are introduced in the future, there's no need to check the version number. So... keep CHECKVERSION in mind for the future, but don't bother with it for the time being. ERRORLEVEL None. If sMINIMUMVERSION is higher than the current Intellicomm version, CHECKVERSION aborts the script. SEE ALSO $BETA_VERSION, $MAJOR_VERSION, $MINOR_VERSION EXAMPLE CHECKVERSION "2" ;is the major version 2.xx or greater? If not the ; script aborts CHECKVERSION "2.0" ;is v2.0x or greater? Intellicomm v2.01 SCRIPT.DOC 54 CHECKVERSION "2.01" ;is v2.01 or greater? CHDIR____________________________________________________________________ SUMMARY CHDIR sNEWDIR DESCRIPTION Changes to a new drive and/or directory. Similar to the DOS 'CHDIR' command, but this command actually changes the current drive as well (DOS's CHDIR simply changes the current directory of a drive but leaves you on the current drive). You can specify a drive alone, a drive and directory, or a directory alone (to change directories on the current drive). You can also specify subdirectories (CHDIR "\ICOM\LST"). ERRORLEVEL 0 = Successful. 1 = Unsuccessful. SEE ALSO $CURDIR EXAMPLE variable old_dir $CUR_DIR ;store current directory in 'old_dir' CHDIR "a:" ;change to drive A: if $ERRORLEVEL = 0 ;successful if 0 dos "" ;DOS shell CHDIR old_dir ;change back to original drive/directory else print "Unable to change to A:" endif CIMPORTNEW_______________________________________________________________ SUMMARY CIMPORTNEW DESCRIPTION Imports all new files lists (*.NEW) from the Intellicomm "List Directory" (\ICOM\LST). This is the same as selecting "Tools | Import BBS Lists (*.NEW)" from the File Tagger. The lists are imported into either the Catalog Name defined on the BIF "Bank/List" screen, or the NEWFILES catalog if no custom catalog is defined. Intellicomm v2.01 SCRIPT.DOC 55 No catalogs need be opened (COPEN) before calling CIMPORTNEW. CIMPORTNEW is automatically executed after all automated jobs, but if you use stand-alone scripts exclusively to carry out your online sessions, you'll have to call it yourself. SEE ALSO CIMPORTTEXT EXAMPLE print "Importing *.NEW" CIMPORTNEW CIMPORTTEXT______________________________________________________________ SUMMARY CIMPORTTEXT [sFILESPEC] [sBIFNAME] DESCRIPTION Imports the file(s) specified by sFILESPEC into the currently open catalog, using the filename/date/size (etc.) positions from the sBIFNAME (a BIF or BIF template) "Bank/List" screen. This is the same as selecting "Tools | Import from Text File" from the File Tagger. If sFILESPEC and/or sBIFNAME is missing, the user is prompted for the information. Wildcards (?, *) may be used in sFILESPEC to specify multiple files (\ICOM\CAP\*.CAP, etc). NOTE: The catalog you wish to import to must be opened first using the COPEN command. ERRORLEVEL 0 Import successful. 1 sFILESPEC was omitted, and the user pressed [Esc] when prompted for a filespec. 2 sFILESPEC not found. 3 sBIFNAME is an invalid BIF. SEE ALSO CIMPORTNEW EXAMPLE copen "NEWFILES" CIMPORTTEXT "C:\ICOM\CAP\ICOM.CAP" "PCB150" cclose Intellicomm v2.01 SCRIPT.DOC 56 CLS______________________________________________________________________ SUMMARY CLS [nCOLOR] DESCRIPTION Clears the current screen WINDOW to nCOLOR if specified, or to the current screen color ($SCRN_COLOR) if nCOLOR is omitted. Also moves the cursor to the top left corner of the WINDOW (same as GOTOXY 1 1). See the COLOR CODES appendix for color numbers to use in nCOLOR. SEE ALSO ERASELINE, SCROLL, $SCRN_COLOR, $TERM_COLOR EXAMPLE CLS $TERM_COLOR ;default terminal color msgwind "You now have a clear screen" CNOTEREC_________________________________________________________________ SUMMARY CNOTEREC [nRECNUM] DESCRIPTION TOGGLES the Noted status of the record specified by nRECNUM (or the current record if nRECNUM is 0 [zero] or omitted). If nRECNUM is specified, that record number is noted/un-noted. If nRECNUM is omitted, the current record (last record obtained via CGETREC) is noted/un-noted. Using CNOTEREC is similar to highlighting a given record in Tagger browse mode and selecting "Note". I.e. if the record is Noted and you CNOTEREC it, it becomes un-noted. If the record is un-noted and you CNOTEREC it, it becomes noted. ERRORLEVEL 0 CNOTEREC was successful. 1 Unable to load nRECNUM (if specified). 2 The current record (or nRECNUM) is marked as "deleted". Deleted records cannot be noted or un-noted. This errorlevel is returned only to eliminate confusion: you should never "undelete" a deleted record to Note it. If the record is deleted, either the user deleted it for a reason; or Icom has already successfully downloaded the file. 3 Unable to switch the Note status (likely a disk write error). If you get this error, try a CPACK to rebuild the indexes. SEE ALSO Intellicomm v2.01 SCRIPT.DOC 57 CTAGREC EXAMPLE 1 copen "newfiles" cgetrec CNOTEREC cclose COPEN____________________________________________________________________ SUMMARY COPEN sCATNAME DESCRIPTION Opens a File Tagger catalog for reading and/or writing (both). sCATNAME is the base name of the catalog, with no drive/path or extension. The catalog must exist in the Catalog Directory ($CAT_DIR). If sCATNAME is not found in $CAT_DIR, it is created. Each catalog is comprised of five files: CATNAME.DBF dBASE-compatible database holds filenames, etc. CATNAME.DBT dBASE-compatible memo file holds EXTENDED file comments. The extended comment is any file description lines after the primary (first) description line. CATNAMET.NDX dBASE-compatible index file holds the information necessary to sort CATNAME.DBF by "Tag Status/Location" (as seen in the File Tagger). CATNAMEC.NDX Same as above but holds information necessary to sort CATNAME.DBF by "Catalog Date/Filesize" (as seen in the File Tagger). CATNAMEN.NDX Another index that holds information necessary to sort CATNAME.DBF by "Filename/File Date" (as seen in the File Tagger). All five files are either opened or created when you call COPEN. No D:\PATH\ or .EXT is accepted in the sCATNAME parameter. All File Tagger catalogs must reside in the Catalog Directory ($CAT_DIR). You're free to keep catalogs in other directories if you like, but if you do you must make sure to COPY or RENAME (move from one directory to another) them before you call COPEN, or change the $DBF_PATH System Variable to point to a different directory (making sure you restore to the original value before your script exits). Further, you cannot open more than one catalog at a time with COPEN, unlike FOPEN which does allow up to 10 files to be open at once. If a catalog is currently open when you call COPEN, it will be automatically closed before the new catalog is opened. Note that when this happens, the contents of the $CXXXX_FLD variables and the file description is NOT cleared. I.e. you can COPEN one catalog, get a record, then COPEN another catalog, CADDREC or CPUTREC (the same record) to copy record from Intellicomm v2.01 SCRIPT.DOC 58 one catalog to another. Here's an example that copies all Tagged files from the NEWFILES catalog into another catalog called CUSTOM: variable last_rec 0 while 1 copen "NEWFILES" csetsort 1 0 ;set to Tag Status/Location sort; Noted files ; come first, Tagged second, then Untagged if last_rec > 0 ;seek back to our original postion cgetrec last_rec ; in NEWFILES if we have a 'last_rec' endif ; (see CTELL below) cgetrec ;get the next record if $ERRORLEVEL <> 0 break ;exit loop at end of catalog if $CTAG_FLD = "N" continue ;skip noted records (Noted sort first) if $CTAG_FLD <> "T" break ;exit loop once Tagged files are done ctell last_rec ;save the current record number copen "CUSTOM" ;close NEWFILES/open a cutom catalog caddrec ;add the Tagged NEWFILES record to the catalog endwhile COPEN also automatically sets the $VIEW_DATE System Variable to the View Date stored in the catalog header (date of last import, or manual View Date set by the user). It also sets the current sort order (CSETSORT) to the order set by the user the last time the catalog was viewed. If you leave $VIEW_DATE alone, ONLY records that were imported on or after the $VIEW_DATE will be returned by CGETREC. To view all records in the database, ASSIGN $VIEW_DATE "19900101" (Jan 1st, 1990... or any date that's older than Intellicomm). For more information on COPEN and File Tagger catalogs in general, please see the INTRODUCTION TO DATABASE COMMANDS section in the file SCRTUTOR.DOC (the script tutorial included with Intellicomm). ERRORLEVEL 0 Catalog successfully opened (may have been created). 1 Unable to open catalog. Either the sCATNAME parameter in the COPEN command was an invalid filename (could not create), or the disk is full, or a disk write error occurred, or the existing catalog is damaged ... or DOS was out of file handles (increase FILES= in your CONFIG.SYS file). COPEN will display a status window indicating the reason for the failure. SEE ALSO CCLOSE EXAMPLE COPEN "NEWFILES" ;open the default 'download' catalog cclose COPEN "FILELIST" ;open the 'upload' catalog Intellicomm v2.01 SCRIPT.DOC 59 cclose ;You can find much more meaningful examples in SCRTUTOR.DOC. COPY_____________________________________________________________________ SUMMARY COPY sSOURCEFILE sTARGETFILE DESCRIPTION Copies sSOURCEFILE (the source filename) to sTARGETFILE (the destination filename), overwriting any file of the same destination filename. Both sSOURCEFILE and sTARGETFILE can (and should) include the full D:\PATH\FILENAME.EXT of the files. If the D: (drive) is omitted in either parameter, the current drive ($CURDRIVE) is assumed. If the \PATH\ (or \PATH1\PATH2\, etc) is omitted in either paramater, the current directory ($CURDIR) is assumed. This command copies either binary or text files, and it maintains the original file date/time stamp (from the source file) on the newly created destination file. This command does NOT create directories. If the directory specified in the destination filename does not exist, the COPY command will fail ($ERRORLEVEL 3). Like the DOS 'COPY' command, if you do not specify drives/directories in the source or destination filenames, the current DOS drive/directory is assumed. So make sure you specify directories unless you're sure of the current directory (use $CURDIR to get the current directory, or CHDIR to change directories first, if necessary). UNLIKE the DOS 'COPY' command, you cannot use wildcards (*, ?) in the source or destination filenames. If you wish to use wildcards, use COMMAND.COM's COPY using the script DOS command (e.g. DOS "copy *.* \temp"). The script equivalent is faster than shelling out to COMMAND.COM though, if you don't need wildcards. ERRORLEVEL 0 Successful copy. 1 Source and destination are the same filename. 2 Unable to find/open the source file. 3 Unable to create the destination file. 4 Disk write error writing to destination (disk full usually, the portion of the destination that was written is deleted). 5 Disk error reading source file, or disk error writing destination file (as above, the portion of the destination written is deleted). 6 Filesize of destination (after copy) is not the same as the size of the source file (the destination file is deleted). SEE ALSO APPEND, APPENDS, APPENDSNC, DIRFIND, DISKFIND, DISKFREE, DOS, EXIST, FILESIZE, FNSTRIP, LOCATEFILE, MKDIR, NOTEXIST Intellicomm v2.01 SCRIPT.DOC 60 EXAMPLE variable source variable destination print "Enter source filename:" gets source 80 ;get 80 characters max print "Enter destination drive, path and filename:" gets destination 80 COPY source destination if $ERRORLEVEL = 0 ;copy successful? print source " copied to " destination else print "Unable to copy file." endif CPACK____________________________________________________________________ SUMMARY CPACK [sCATALOG_NAME] DESCRIPTION Physically removes any records marked as "deleted" from sCATALOG_NAME (or the currently open catalog, if sCATALOG_NAME is omitted). Also removes any unattached extended file descriptions from the .DBT, and rebuilds the three indexes (.NDX) related to sCATALOG_NAME. ERRORLEVEL SEE ALSO CDELREC, CPURGE EXAMPLE 1 copen "NEWFILES" cpurge ;kill old records as configured in the Icom main setup ; (optional) CPACK cclose EXAMPLE 2 CPACK "NEWFILES" ;COPEN/CCLOSE are done by CPACK. CPURGE___________________________________________________________________ SUMMARY CPURGE [sCATNAME] DESCRIPTION Intellicomm v2.01 SCRIPT.DOC 61 Marks untagged/noted records in sCATNAME as deleted. If sCATNAME is omitted, the currently open catalog is assumed. CPURGE uses two Icom main setup variables to perform the purge: *prgnote (Tagger Settings, item "Purge Noted # Days Old") *purge (Tagger Settings, item "Purge Untagged # Days Old") If *prgnote is 0 (zero), no Noted records are deleted. If *purge is 0 (zero), no Untagged records are deleted. SEE ALSO CDELREC, CPACK EXAMPLE CPUTDESC_________________________________________________________________ SUMMARY CPUTDESC sNEWTEXT nLINE DESCRIPTION Appends a new description line (if nLINE is 0), or replaces an existing description line (if nLINE is 1 or greater) to the currently loaded file description. Before using CPUTDESC a catalog must be opened with COPEN, and a record must be loaded using CGETREC. CPUTDESC does not modify the description on-disk in the catalog -- it works only with the description memory buffer, similar to the catalog $CXXXX_FLD variables. To save a description you modify with CPUTDESC, you must save the catalog record back (from memory) to disk with CPUTREC. Technically what CPUTDESC does is to first locate description line number nLINE in the description memory buffer (or seek to the END of the description of nLINE is 0). It then deletes the existing text (in the memory buffer ONLY) on that line, then inserts sNEWTEXT (if any). If sNEWTEXT is blank ("") then line number nLINE is simply removed. Note that you may wish to use CFORMATDESC to re-format the description to a different line length before using CGETDESC or CPUTDESC. Descriptions are formatted to a maximum of 45 characters per line by CGETREC. ERRORLEVEL 0 Description line number nLINE was non-zero, and the line did exist. The contents of that line was either replaced with sNEWTEXT, or the line was removed (if sNEWTEXT was blank). 1 There was no description line number nLINE, and nothing was done. sNEWTEXT was not added. It would be a programming error to get this error code, since you shouldn't be replacing existing description Intellicomm v2.01 SCRIPT.DOC 62 lines until you know (a) how many lines already exist, and (b) what the contents of those lines was. It would make no sense to do this: CGETREC CPUTDESC "Replace line 4 with this text." 4 Since the only time you'd want to replace line 4 is if you KNEW that there was a line 4, and you knew what it contained. If you 'did' do something like the above, and line 4 didn't exist in the description, you'd get $ERRORLEVEL 1 and "Replace line 4 with this text." wouldn't be added. It would make more sense to do this: cgetrec cgetdesc myvariable 4 ;get line 4 (CGETDESC also sets $ERRORLEVEL) if $ERRORLEVEL = 0 ;did line 4 exist? (yes if $ERRORLEVEL = 0) if myvariable = "Some text you want to replace." ;NOW you can go ahead specifying line 4, since you know it ; exists, and you know that the line contained some text you ; didn't want. CPUTDESC "Replace line 4 with this text." 4 ;Alternatively, if you wanted to just kill the text on line 4 ; that you didn't want: CPUTDESC "" 4 cputrec ;write the new description to disk endif endif You'd never get $ERRORLEVEL 1 after CPUTDESC using a technique similar to the above, since you've already obtained line 4, you know what it contains, and you're replacing it. Really the only other use for CPUTDESC is to *add* text to an existing description (or to build an entirely new description). In either case, you needn't specify a line number at all: CPUTDESC "Add this to the end of the description." 0 Or simply leave the 0 off: CPUTDESC "Add this to the end of the description." TIP: To replace an entire description, use CCLEARDESC (get rid of the existing description) then 'CPUTDESC "new data" 0' (add the new one). You can use 'CPUTDESC "new data" 0' multiple times in a loop (or anywhere else) if necessary, to continue adding new lines of text. SEE ALSO CCLEARDESC, CPUTDESC, CPUTREC EXAMPLE copen "FILELIST" cgetrec Intellicomm v2.01 SCRIPT.DOC 63 cputdesc "Line added complements of CPUTDESC" 0 cputrec Please see POSTFILE.SCR for a more meaningful example of CPUTDESC. CPUTREC__________________________________________________________________ SUMMARY CPUTREC [nRECNUM] DESCRIPTION Writes the current record to disk, and updates the catalog indexes if necessary. CPUTREC is to be used after COPEN/CGETREC when one or more of the $CXXXX_FLD variables has been modified or CPUTDESC has been used. If nRECNUM is specified, it must be a valid record number for the currently open catalog. Normally you'll omit nRECNUM, which simply updates the last record loaded by CGETREC. ERRORLEVEL 0 The record was written to disk. 1 Error updating the record. SEE ALSO CADDREC EXAMPLE copen "NEWFILES" cgetrec date2cdate $CCDATE_FLD $DATE ;assign today's date to the Catalog Date cputdesc "Add this to the file description" 0 CPUTREC ;updates the Catalog Date, description, and all indexes cclose CSAVEBMARK_______________________________________________________________ SUMMARY CSAVEBMARK [nBOOKMARK_RECNUM] DESCRIPTION Saves the current record (or nBOOKMARK_RECNUM if specified) as the bookmark. The next time the user views the catalog in the File Tagger, the bookmarked record will be automatically hilighted. SEE ALSO CSAVESORT, CSAVEVDATE Intellicomm v2.01 SCRIPT.DOC 64 EXAMPLE CSAVESORT________________________________________________________________ SUMMARY CSAVESORT DESCRIPTION Saves the current sort order, as set by CSETSORT. The next time the user views the catalog (or the next time it is COPENed) the sort order saved by CSAVESORT will be used. SEE ALSO CSAVEBMARK, CSETSORT, CSAVEVDATE, $CSORT_DIR, $CSORT_ORDER EXAMPLE COPEN "NEWFILES" CSETSORT 3 1 ;sort by Filename/Date, Reversed CSAVESORT CCLOSE CSAVEVDATE_______________________________________________________________ SUMMARY CSAVEVDATE [sVIEWDATE] DESCRIPTION Saves the current $VIEW_DATE (or sVIEWDATE if specified) in the catalog header. The next time the user views the catalog (or the catalog is COPENed) the View Date saved by CSAVEVDATE will be in effect. NOTE 1: If sVIEWDATE is used, it must be specified in dBASE date format YYYYMMDD (YearMonthDay). Use DATE2CDATE to convert $DATE (today's date) to dBASE format. NOTE 2: CSAVEVDATE "19800101" (January 1st, 1980) will effectively disable the 'View Date' feature, allowing ALL records in the catalog to be displayed. No records should have a Catalog Date older than 1980. SEE ALSO CSAVEBMARK, CSAVESORT, $VIEW_DATE CSEEK____________________________________________________________________ SUMMARY CSEEK [nNUMRECS] [nORIGIN] Intellicomm v2.01 SCRIPT.DOC 65 DESCRIPTION This advanced command moves the 'record pointer' of the currently open catalog. The record pointer holds the record number that CGETREC will load next. nNUMRECS specifies the number of records from nORIGIN to seek (a positive number seeks FORWARD, a negative number seeks BACKWARDS), nORIGIN specifies the origin of the seek as follows: 0 = From the beginning of the catalog. 1 = From the current record. 2 = From the end of the catalog. 3 = Seek to an absolute record number (the record number specified by nNUMRECS). NOTE 1: CSEEK will confuse the daylights out of you until you read the section "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC. You must have a good grasp of the CSETSORT / CGETREC commands before using CSEEK. NOTE 2: CSEEK will be used very infrequently, and most times you'll just CSETSORT then CGETREC to get catalog records (CGETREC calls CSEEK 1 0 automatically to seek to the next record). CSEEK is provided for advanced use only. ERRORLEVEL 0 CSEEK was successful. 1 CSEEK was unsuccessful (no such record). SEE ALSO CTELL EXAMPLE COPEN "NEWFILES" CSETSORT -1 0 ;unsorted (no index or View Date in effect) CSEEK 0 2 ;seek to the end of the catalog CSETSORT_________________________________________________________________ SUMMARY CSETSORT [nSORTORDER] [nDIRECTION] DESCRIPTION Sets the sort order and direction for the currently open catalog as follows: nSORTORDER: -1 = Unsorted 1 = Tag Status/Location Intellicomm v2.01 SCRIPT.DOC 66 2 = Catalog Date/Filesize 3 = Filename/File Date nDIRECTION: 0 = Forward 1 = Reversed If nSORTORDER or nDIRECTION are 0 (or omitted), CSETSORT displays a menu of the available sort orders / directions, and prompts the user for input. SEE ALSO CSAVESORT, SCRDEMO.SCR (CSETSORT is used by SCRDEMO.SCR) EXAMPLE 1 COPEN "NEWFILES" CSETSORT ;prompt the user for the sort order/direction ... CCLOSE EXAMPLE 2 COPEN "NEWFILES" CSETSORT 3 0 ;sort by Filename/File Date, Forward ... CCLOSE CTAGALL__________________________________________________________________ SUMMARY CTAGALL DESCRIPTION BETA NOTE: Command not implemented yet. ERRORLEVEL SEE ALSO EXAMPLE CTAGREC__________________________________________________________________ SUMMARY CTAGREC [nRECNUM] [nMODE] [sBIF_ID[;sBIF_ID]...] DESCRIPTION Intellicomm v2.01 SCRIPT.DOC 67 TOGGLES the Tag status of the record specified by nRECNUM (or the current record if nRECNUM is 0 [zero] or omitted). If nRECNUM is specified, that record number is tagged/untagged. If nRECNUM is omitted, the current record (last record obtained via CGETREC) is tagged/untagged. Using CTAGREC is similar to highlighting a given record in Tagger browse mode and selecting "Tag". I.e. if the record is Tagged and you CTAGREC it, it becomes untagged. If the record is untagged and you CTAGREC it, it becomes Tagged. It works a little differently if working with the FILELIST (upload) catalog, however. See below. [nMODE] and [sBIF_ID[;sBIF_ID]...] are only valid if the FILELIST (upload) catalog is open, and they are used to add the "Upload Pending" strings you see in the File Tagger after you Tag a file for uploading. If sBIFID is blank ("") then all Upload Pending BIFID's are removed from the record, and the record is untagged. If one or more BIFID's are specified (in the format "BIFID" or "BIFID1;BIFID2;BIFID3"...etc) then nMODE comes into play as follows: nMODE = -1 the passed BIFID(s) are removed from ULPEND (if found). nMODE = 0 the passed BIFID(s) replace the existing ones. nMODE = 1 the passed BIFID(s) are appended to the existing ULPEND. See the example for details. ERRORLEVEL 0 CTAGREC was successful. 1 Unable to load nRECNUM (if specified). 2 The current record (or nRECNUM) is marked as "deleted". Deleted records cannot be tagged/untagged. This errorlevel is returned only to eliminate confusion: you should never "undelete" a deleted record to Tag it. If the record is deleted, either the user deleted it for a reason; or Icom has already successfully downloaded the file. 3 Unable to switch the Tag status (likely a disk write error). If you get this error, try a CPACK to rebuild the indexes. SEE ALSO CNOTEREC EXAMPLE 1 copen "newfiles" cgetrec CTAGREC cclose EXAMPLE 2 ;Tagging files for upload is only useful to have Icom itself upload ; the files (i.e. using the PREJOB.SCR to Tag files for upload prior ; to an automated job that had one or more "Upload tagged files" Intellicomm v2.01 SCRIPT.DOC 68 ; tasks). Uploading files (handling the entire process) from a script ; and trying to use the FILELIST catalog would be a very complex ; procedure, and it is not recommended. copen "filelist" ;open the upload catalog cgetrec CTAGREC 0 1 "JOESBBS" ;tag for uploading to joesbbs... if JOESBBS ; already exists in the "Upload Pending" string, ; no action is taken. If JOESBBS doesn't exist, ; it is appended (Upload Pending:ABBS;JOESBBS). CTAGREC 0 -1 "JOESBBS" ;JOESBBS is removed from the "Upload Pending" ; string if it exists. If no more BIFID's remain ; in the Upload Pending string, the record is ; also automatically Untagged. CTAGREC 0 0 "JOESBBS" ;all other BIFID's in the Upload Pending string ; (if any) are removed, and JOESBBS is added. CTAGREC 0 0 "" ;all BIFID's are removed from the Upload Pending ; string, none are added, and the record is ; Untagged cclose CTELL____________________________________________________________________ SUMMARY CTELL vCUR_REC DESCRIPTION Stores the record number of the currently loaded record in variable vCUR_REC (a user-defined variable, defined using the VARIABLE command). CTELL is useful for saving your position in a catalog. Use CTELL to get the current record number, then use CSEEK vCUR_REC 3 (seek to absolute record number) to seek back to it later. NOTE: You must use CTELL before using CDELREC (delete a catalog record), since you must specify a record number with CDELREC. EXAMPLE variable recnum copen "NEWFILES" CTELL recnum ;store current position in 'recnum' ... ;CGETREC and otherwise fiddle around cseek recnum 3 ;seek back to original position ... ;do whatever needs doing CCLOSE SEE ALSO Intellicomm v2.01 SCRIPT.DOC 69 CURSORLARGE______________________________________________________________ CURSORSMALL______________________________________________________________ SUMMARY CURSORLARGE CURSORSMALL DESCRIPTION CURSORLARGE changes the cursor to large (half character height) while CURSORSMALL changes the cursor to small (underline). If the cursor is hidden (CURSOROFF, etc) when either command is called, it will be re- displayed. Note that the BOXGETS and GETS/GETSXY commands do not use the current cursor size, and they display the cursor as large/small according to the current Insert/Typeover status set by the user. SEE ALSO CURSORPOP, CURSORPUSH, CURSOROFF, CURSORON EXAMPLE CURSORLARGE pause "Press a key... " CURSORSMALL CURSOROFF________________________________________________________________ CURSORON_________________________________________________________________ SUMMARY CURSOROFF CURSORON DESCRIPTION CURSOROFF hides the screen cursor, while CURSORON re-displays a hidden screen cursor. SEE ALSO CURSORONOFF, CURSORPUSH, CURSORPOP EXAMPLE CURSOROFF pause "Press any key to continue..." CURSORON CURSORONOFF______________________________________________________________ SUMMARY Intellicomm v2.01 SCRIPT.DOC 70 CURSORONOFF nSTATE DESCRIPTION Turns the cursor on or off, according to nSTATE. If nSTATE is 0 (zero) the cursor is turned off (hidden). If nSTATE is non-zero the cursor is turned on (unhidden). SEE ALSO CURSORON, CURSOROFF EXAMPLE pause "Press a key to hide the cursor..." CURSORONOFF 0 pause "Press a key to unhide the cursor..." CURSORONOFF 1 CURSORPOP________________________________________________________________ CURSORPUSH_______________________________________________________________ SUMMARY CURSORPOP CURSORPUSH [nNEWSTATUS] DESCRIPTION CURSORPUSH saves the position (screen x/y coordinate), size, and on/off status of the cursor, and optionally sets a new on/off status. If nNEWSTATUS is omitted, the cursor status (on/off) remains unchanged after CURSORPUSH. If nNEWSTATUS is specified, a value of -1 means to leave the cursor status as is (same as not specifying it) while a value of 0 (zero) means to turn the cursor off (same as CURSOROFF) while a value of 1 (one) means to turn the cursor on (same as CURSORON). You can call CURSORPUSH up to 16 times (if necessary, saving different cursor states/positions) before calling CURSORPOP. If you call CURSORPUSH 17 times without a single CURPOP, you'll get a CURSORPUSH Stack Overflow error and your script will abort. CURSORPOP restores the cursor to the location, size and on/off status it had before the *last* CURSORPUSH (last in, first out). SEE ALSO CURSORON, CURSOROFF EXAMPLE vpush ;save contents of the video screen CURSORPUSH ;save cursor state Intellicomm v2.01 SCRIPT.DOC 71 cursoron ;turn cursor on cursorlarge ;large cursor cls ;clear screen, GOTOXY 1 1 pause "Press a key to restore..." vpop curpop pause "Back to normal..." DATE2CDATE_______________________________________________________________ SUMMARY DATE2CDATE vCDATE sDATE DESCRIPTION Converts sDATE (a date in the format returned by $DATE or $FDATE) to a dBASE style date (YYYYMMDD) and stores in vCDATE. SEE ALSO CDATE2DATE EXAMPLE 1 CGETREC DATE2CDATE $CCDATE_FLD $DATE ;assign today's date to Catalog Date CPUTREC EXAMPLE 2 DATE2CDATE $VIEW_DATE $DATE ;assign today's date to View Date CSAVEVDATE ;save in catalog header DEBUG____________________________________________________________________ SUMMARY DEBUG nSTAT | vVARIABLE DESCRIPTION | above means 'OR'. You can use 0, 1, 2 (nSTAT), OR a variable name (vVARIABLE). The script debugger is explained in detail in SCRTUTOR.DOC. DEBUG 0 turns debugging off, DEBUG 1 turns step-by-step debugging on, DEBUG 2 turns 'animated' debugging mode on. A variable name, if specified, pauses the script and displays the contents of the variable. All can be very useful in finding script logic errors. EXAMPLE Intellicomm v2.01 SCRIPT.DOC 72 variable count DEBUG 2 ;turn 'animate' mode on... displays each script line ; on the status line at the rate of two lines per ; second, prior to executing the line. assign count 0 while count < 10 inc count endwhile DEBUG count ;displays the contents of 'count' (would be 10) DEBUG 1 ;turn 'step-by-step' debugging on... displays each ; script line on the status line, then pauses until ; you press [Space] or [Enter] before executing the ; line. while count < 10 ;this displays "WHILE 10 < 10" (the variable's value is inc count ; displayed, rather than showing the variable name). endwhile DEBUG 0 ;turn debug mode off. return DEC______________________________________________________________________ SUMMARY DEC vNUM DESCRIPTION Subtracts 1 from the contents of the specified variable vNUM. If the variable contained the number 10, DEC would decrement it to 9. If the variable contained 0, DEC would changes it to -1. If the variable contained TEXT instead of a number, iot will contain -1 when DEC finishes with it (since 0 is assumed if vNUM is missing, or if it's non- numeric). DEC first converts the variable to a number (text translates to the number 0), then subtracts 1 from that number. SEE ALSO ADD, SUB, INC EXAMPLE variable count 10 ;define variable 'count', assign 10 to it ;count from 10 down to 1 while count > 0 ;while count is greater than 0, do to endwhile print count ;print the contents of 'count' DEC count ;count = count - 1 endwhile Intellicomm v2.01 SCRIPT.DOC 73 DELAY____________________________________________________________________ _ SUMMARY DELAY nTENTHS DESCRIPTION Delays execution of the script for nTENTHS tenths of a second. So to delay for one second you'd use DELAY 10, to delay for a minute you'd use DELAY 600, and so forth. NOTE: DELAY updates the terminal screen with incoming characters from the BBS while paused. To pause and freeze the display, use DELAYNC. SEE ALSO DELAYNC, PAUSE, WAITUNTIL EXAMPLE send "D" ;send a [D]ownload command to the BBS delay 10 ;pause for a second to wait for the filename prompt send "ICOM201A.ZIP" delay 50 ;wait 5 seconds for the D/L to start download "Z" ;download using Zmodem DELAYNC__________________________________________________________________ SUMMARY DELAYNC nTENTHS DESCRIPTION Delays execution of the script for nTENTHS tenths of a second. So to delay for one second you'd use DELAYNC 10, to delay for a minute you'd use DELAYNC 600. NOTE: The NC in DELAYNC stands for 'N'o 'C'omm. updating. DELAYNC does NOT update the terminal screen with incoming characters from the BBS during the delay. To allow incoming characters to be displayed during a delay, use the DELAY command. You won't actually lose any characters from the BBS during a DELAYNC; Icom's interrupt handler is still getting characters from the COM port and storing them in its internal buffer (which defaults to 4 kilobytes in size). It just doesn't update the terminal screen with the incoming characters. SEE ALSO DELAY, PAUSE, WAITUNTIL EXAMPLE Intellicomm v2.01 SCRIPT.DOC 74 ;^M^J is carriage return/line feed (move to a new line) print "^M^JNOTE: <some important message>" DEL___________________________________________________________________ DELETE________________________________________________________________ SUMMARY DEL sFILESPEC DELETE sFILESPEC DESCRIPTION Similar to the DOS 'DEL' and 'DELETE' commands, this script command deletes a specified filespec from the disk. You are allowed to use wildcards (*, ?) in the filespec portion if necessary. You cannot delete directories with the DELETE command (use RMDIR to delete directories). You may omit the drive and/or directory in sFILESPEC if the file(s) to be deleted are in the current DOS directory ($CURDIR), but if you use this method make sure you KNOW which directory you're in first by using CHDIR. Icom changes directories for various purposes during its course of operation, and you really can never be sure which directory you're in when your script is running, unless you check $CURDIR or use CHDIR at some point before the DELETE command. WARNING: Do not attempt to delete a file that is currently 'open' with the FOPEN command or CAPTURE command. It can cause sharing violations and/or exception 13's. You must CCLOSE (catalogs, if you COPENed one) FCLOSE (regular files, if you FOPENed the file) or CAPCLOSE (the capture file) before deleting them. ERRORLEVEL 0 File(s) successfully deleted. 1 Error deleting one or more files (file not found, or the file's "read only" attribute is set). $ERRORLEVEL can be above 1 (2,3,4,etc) if more than one error occurs ... it is set to the number of files that could not be deleted. SEE ALSO DISKFIND, DOS, EXIST, LOCATEFILE, NOTEXIST, RENAME, RENUMBER, RMDIR EXAMPLE ;CAPTURE always appends (adds to the end) of existing files. If ; you wish to create a new capture file, simply DELETE the existing ; file prior to calling CAPTURE. CAPCLOSE ;always make sure it's closed... DELETE "\ICOM\CAP\ICOM.CAP" ;or use DELETE $CAP_NAME CAPTURE "\ICOM\CAP\ICOM.CAP" ;or use CAPTURE $CAP_NAME Intellicomm v2.01 SCRIPT.DOC 75 DIAL_____________________________________________________________________ SUMMARY DIAL [sBBSNAME] [nEXACTMATCH] DESCRIPTION Dials one or more BIFs, or a specific telephone number, or displays the BBS Directory for user input. Variation 1, dialing one or more BIFs: If sBBSNAME is specified and nEXACTMATCH is omitted, DIAL switches to the BBS Directory (the equivalent of pressing [Alt-D] in Icom), selects "Find" from the BBS Directory menu, enters sBBSNAME, then selects "Find all/Tag all". Any/all BIFs matching sBBSNAME are then tagged and dialed. If nEXACTMATCH is specified (as a non-zero number) then "Find all/Tag all" is NOT in effect and only one BIF is tagged: its description must match sBBSNAME exactly. Variation 2, dialing a specific telephone number: If sBBSNAME contains "^M" as its first character, a specific telephone number is dialed (similar to selecting "Manual" from the BBS Directory; e.g. DIAL "^M555-1234"). Variation 3, manual user input: If both sBBSNAME and NEXACTMATCH are omitted, the BBS Directory is displayed for manual user input (the same as pressing [Alt-D]). Only when DIAL connects (or aborts due to an error) does your script continue running. If multiple BBS's are tagged (when not specifying nEXACTMATCH or a manual number) you can check the $BIF_NAME System Variable when DIAL returns, to see which bulletin board you are connected to. NOTE: Using the DIAL or REDIAL commands cause any previously defined WHEN commands to be lost. All WHENs are cleared when DIAL exits. TIP: You can use a single character as the sBBSNAME parameter if you like. By placing specific characters in your BIF descriptions (@, !, #, etc) you could set up a system whereby different groups of BIFs could be dialed under different circumstances. You could dial one set on weekdays by putting, say, ! in the descriptions of the BIFs you want to dial on weekdays, then using DIAL "!". You could dial another set on weekends by placing @ in those descriptions then using DIAL "@". The $DOW (Day Of Week) System Variable will tell your script what day it is. You could also place multiple symbols in some BIFs (!@) to have certain BIFs dialed on both weekdays and weekends, etc. The same sort of thing can be done using the time of day ($HOUR, $MIN, $SEC) or day of month ($DAY) to have various BBS's called at certain times of the day, or on Intellicomm v2.01 SCRIPT.DOC 76 certain days of the month. Regardless of how DIAL is used, the $ERRORLEVEL System Variable is set to 0 if dialing is successful and a connection is established. At that point it's up to your script to perform the logon. If you'd rather have Icom perform the logon (to take advantage of the BIF, and possible logons through the PC-Pursuit or iNet long-distance services), then you shouldn't use a DIAL command in your script. Rather you should define a job such as this: Call <some BBS> CC: @MYSCRIPT Send message replies ...etc. I.e. use an automated job to perform the dialing/logon, then run your script via the "Custom Command" task. Icom will take care of both the logon and logoff in these cases, assuming the BIF is set properly. If possible, when using Custom Commands to execute scripts, you should have your script return to one of the BBS 'main' menus before it exits and returns control to Intellicomm (the Main Menu A, Main Menu B, Message Menu, Bank Menu, or File Menu prompt). Icom does perform a check of the current BBS prompt after Custom Commands to locate its position, but if you leave it in an area of the BBS that it isn't familiar with (i.e. a DOOR or sub-menu other than one of the menus mentioned above) it may not be able to get back to a menu it recognizes, and thus may be forced to disconnect and call back, wasting online time (though your script would not be executed after the call-back; jobs are flagged as 'complete' when they finish). ERRORLEVEL 0 Dial/connection successful. 1 No connection (the user may have pressed the [Esc] key, or the number may have been tried to the "Max. Redials" for the BIF, and too many other possibilities to list... but you didn't get connected). 2 A "Search String" was specified, but no matches were found in any of the BIF descriptions. If this happens Icom also displays a status window stating "Text not found". The easiest way to check whether DIAL was successful is to use the OFFLINE command after DIAL to check the connect status. Example: DIAL "My Favorite BBS" 1 offline exit ;exit the script if offline SEE ALSO REDIAL EXAMPLE DIAL "Joe's BBS" if $ERRORLEVEL <> 0 return ;exit if $ERRORLEVEL is not equal to 0 Intellicomm v2.01 SCRIPT.DOC 77 when "Name?" send "John Smith" when "Password?" send "mypassword" waitfor "Selection:" 60 return ;leaves the user in Manual Terminal mode if ; online when the script ends ADVANCED EXAMPLE DIAL "BBS" ;tags/dials ALL BIFs with 'BBS' in their descriptions while 1 ;enter an endless loop (until BREAK) switch $BIF_NAME ;check which BIF 'DIAL' connected to case "JOESBBS" gosub handle_joes_bbs endcase case "THEBBS" gosub handle_the_bbs endcase ;subroutines not given... It is assumed they would perform the ; logon/online session/logoff then RETURN for the redial endswitch hangup redial ;dial any BIFs still tagged offline break ;exit loop if not connected (nothing left to dial) endwhile DIREXIST_________________________________________________________________ SUMMARY DIREXIST sDIRECTORY_NAME cCOMMAND DESCRIPTION Executes cCOMMAND if sDIRECTORY_NAME (a \DIRECTORY\SUBDIR or D:\DIRECTORY\, etc) exists; skips cCOMMAND if sDIRECTORY_NAME does not exist. SEE ALSO EXIST, NOTEXIST, FINDFIRST, FINDNEXT EXAMPLE DIREXIST $DL_DIR goto start mkdir $DL_DIR start: DISKFIND_________________________________________________________________ SUMMARY DISKFIND vFILEFOUND sFILESPEC ... DESCRIPTION Intellicomm v2.01 SCRIPT.DOC 78 Searches the specified disk drive for sFILESPEC in the format D:FILENAME.EXT. If a file is found matching the filespec its full pathname (D:\PATH\FILENAME.EXT) is stored in vFILEFOUND. sFILESPEC may contain wildcards (*, ?) and the disk drive is optional. If no disk drive is specified the current drive is assumed. Directory names (\PATH\) should not be specified in sFILESPEC, as the purpose of DISKFIND is to locate a file when you DON'T know which directory the file is in. Every directory on the drive is searched and thus you simply give DISKFIND a filename (or filespec such as "C:ICOM*.*"). Directories will be ignored if specified. The search begins at the root directory of the drive and traverses through directories and subdirectories as they are encountered. ERRORLEVEL 0 The file was found and its full pathname is stored in vFILEFOUND. 1 The file was not found (vFILEFOUND is empty). 2 An invalid drive was specified (vFILEFOUND is empty). SEE ALSO LOCATEFILE EXAMPLE variable findme "*.DBF" ;define variable 'findme' assign *.DBF to it DISKFIND findme findme ;you can store the result in the same variable if $ERRORLEVEL = 0 print "Found a dBASE database (or Icom File Tagger catalog):" print findme else msgwind "*.DBF not found" endif DISKFREE_________________________________________________________________ SUMMARY DISKFREE vBYTESFREE [sDRIVE] DESCRIPTION Places the number of free bytes available on drive sDRIVE in vBYTESFREE. If sDRIVE is omitted the current drive is assumed. ERRORLEVEL None. If sDRIVE is invalid, vBYTESFREE is set to -1 (minus one). Intellicomm v2.01 SCRIPT.DOC 79 EXAMPLE variable cfree DISKFREE cfree "C" ;the colon (C:) is not needed print "Drive C: has " cfree " bytes free." DIV______________________________________________________________________ SUMMARY DIV vQUOTIENT nDIVIDEND nDIVISOR DESCRIPTION Divides nDIVIDEND by nDIVISOR and stores the result (rounded; no remainder) in vQUOTIENT. SEE ALSO ADD, MUL, SUB EXAMPLE variable result ADD result 10 5 ;stores 10 divided by 5 (2) in variable 'result' print result DOS______________________________________________________________________ SUMMARY DOS [sCOMMAND ...] DESCRIPTION Executes an external program. If sCOMMAND is omitted a DOS shell is performed (the same as pressing [Alt-J]). The DOS command calls COMMAND.COM to executed sCOMMAND and thus batch files (.BAT) can be executed, and redirection (>, >>, <) and/or pipes (|) can be used in the command no different than if you were sitting at the C:> prompt. NOTE: Intellicomm will swap itself out of base memory before executing sCOMMAND depending upon the setting of the *swpon (Swap On) System Variable defined by the user in the main setup: *swpon = 0 No swapping *swpon = 1 When not connected *swpon = 2 Connected or not See the System Variables section below for more information on *swpon. To force a Swap regardless of the setting of *swpon specify "SW:" as the first item in sCOMMAND. To force NO swapping regardless of the setting of *swpon specify "NS:" as the first item in sCOMMAND. See the example Intellicomm v2.01 SCRIPT.DOC 80 for details. ERRORLEVEL -3 Not enough memory to load COMMAND.COM. -2 No file handles to open COMMAND.COM (increase FILES= in CONFIG.SYS). -1 COMMAND.COM could not be located. 0+ (Zero or greater) COMMAND.COM was located and executed. Whether the DOS sCOMMAND was carried out successfully cannot be determined as COMMAND.COM does not return an errorlevel to indicate external program errors. Use the EXEC command when you must determine the exit code of a program. SEE ALSO EXEC EXAMPLE DOS ;DOS shell, swapping determined by *swpon DOS "SW:" ;DOS shell, force Icom to swap out DOS "NS:" ;DOS shell, force Icom NOT to swap out DOS "123.EXE" ;COMMAND.COM seaches the PATH for 123.EXE and executes ; it if found. *swpon determines swapping. DOS "NS:LIST.COM" ;Execute LIST.COM, do not swap out. DOS "SW:C:\BAT\DELUXE.BAT" ;Execute C:\BAT\DELUXE.BAT, swap out first DOS "DIR > DIRLIST.TXT" ;Execute a 'DIR'ectory command, redirect ; output to a file called DIRLIST.TXT ;Get user input and execute the command variable command boxgets command "DOS Command" "Enter a DOS command to execute" 64 dos command DOWNLOAD_________________________________________________________________ SUMMARY DOWNLOAD sPROTOCOL [sFILENAME] DESCRIPTION Downloads sFILENAME (if specified) using transfer protocol sPROTOCOL. sFILENAME is required by the protocols which have an asterisk following their name below. sFILENAME can be specified for protocols which do not require a filename to be specified (Ymodem/Zmodem): if you pass a filename to these protocols, the first file accepted will use the filename you specify. Normally you will not specify sFILENAME when calling Ymodem or Zmodem, since the proper filename is passed by the sending protocol, but it can be useful to 'force' a specific filename Intellicomm v2.01 SCRIPT.DOC 81 under some circumstances. sPROTOCOL is the 'hotkey' used to select the protocol from the protocol menu from Terminal Mode (including external protocols, if any are installed): "A" = ASCII* "R" = Relaxed Xmodem* "X" = Xmodem* "1" = Xmodem-1K* "K" = Xmodem-1K-G* "Y" = Ymodem "G" = Ymodem-G "Z" = Zmodem NOTE: Ymodem, Ymodem-G and Zmodem are 'batch' transfer protocols. This means that they can download several files using a single DOWNLOAD command. ERRORLEVEL 0 Transfer successful (if batch, all files were downloaded) 1 User abort ([Esc] pressed) 2 Connection lost 3 Remote (BBS protocol) cancelled 4 Disk read/write error 5 Bad external protocol (if called an external and not found) 6 Flow control error (not relevant to DOWNLOAD, only UPLOAD) 7 Miscellaneous protocol error (too many timeouts, etc). SEE ALSO UPLOAD EXAMPLE 1 variable filename assign filename "FILENAME.ZIP" ;some filename to download send "D " filename ;tell BBS to download waitfor "(Ctrl-X) Aborts" ;wait for 'begin transfer' prompt DOWNLOAD "1" filename ;Download FILENAME.ZIP using Xmodem-1K EXAMPLE 2 send "D FILE1.ZIP FILE2.ZIP FILE3.ZIP Z" ;PCBoard (and others) Download ; several files using Zmodem waitfor "(Ctrl-X) Aborts" DOWNLOAD "Z" ;Download one or more files using Zmodem EDIT_____________________________________________________________________ SUMMARY Intellicomm v2.01 SCRIPT.DOC 82 EDIT [sFILENAME] [nLINENUM] DESCRIPTION Enters Icom's internal Text Editor, or the external editor defined by the user (main setup/Filenames and Paths screen, main setup variable *editor). sFILENAME is an optional [D:][\PATH\]FILENAME[.EXT] to load (a filename with optional drive, path and extension) to load. nLINENUM is only valid when *editor is blank (no external editor), and it specifies an optional line number to position the cursor to after loading sFILENAME. NOTE: If you want to ensure use of Icom's internal Text Editor, simply save the *editor main setup variable, clear it, then call EDIT. Example: variable filename $SCRIPT_DIR "SCRDEMO.SCR" variable oldeditor *editor ;save external editor (if any) assign *editor "" ;clear external editor EDIT filename 100 ;edit C:\ICOM\SCR\SCRDEMO.SCR, position to ; line 100 assign *editor oldeditor ;restore original external editor This should only be done when you must seek to a specific line number in a file. You should otherwise let the user edit files in his preferred external text editor. SEE ALSO LIST EXAMPLE variable filename $HOME_DIR "POSTMAIL.BAT" pause "Press a key to edit POSTMAIL.BAT..." edit filename ERASELINE________________________________________________________________ SUMMARY ERASELINE nLINE [nCOLOR] DESCRIPTION Clears screen line nLINE changing the line to nCOLOR. If nCOLOR is omitted $SCRN_COLOR is assumed. nLINE can be any number from 1 (top line) to $SCRN_HEIGHT (the bottom screen line). On EGA/VGA displays, $SCRN_HEIGHT can be 25, 42, or 50. On other displays the screen height is limited to 25 lines. Note that the status line is normally on the last line of the screen ($SCRN_HEIGHT) and CAN be overwritten by ERASELINE if desired. Intellicomm v2.01 SCRIPT.DOC 83 ERASELINE does not move the screen cursor. Use 'GOTOXY 1 nLINE' (where nLINE is the line specified in ERASELINE) if you wish to move the cursor to the beginning of the blank line. SEE ALSO CLS, SCROLL, VPUSH, VPOP, $SCRN_COLOR, $SCRN_HEIGHT EXAMPLE ERASELINE 1 $TERM_COLOR ;clear first line on screen to $TERM_COLOR printraw -1 1 $TERM_COLOR "Centered Title on line 1" ;-1 centers line ERASELINE 2 ;clear line 2 to the current screen color EXEC_____________________________________________________________________ SUMMARY EXEC [SW:|NS:][D:\PATH\]FNAME[.EXT] [PARM ...] [>redirect | >>redirect] (Sorry! It looks terribly complicated, but it isn't as bad as you think.) DESCRIPTION EXEC executes file FNAME, passing any specified parameters to it, then returns to the script (continuing at the next script line, if any). FNAME is the external program to execute, and can include a D:\PATH\ (or just a \PATH\) if the program to execute is not on the DOS PATH. You may include an extension as well, but it must be either .COM or .EXE. .BAT files are not supported by EXEC (use the DOS command to execute DOS commands such as 'DIR', etc., or batch files). You may precede FNAME with SW: (Swap) to force Icom to swap itself out of memory (to XMS/EMS if available, or to disk if not) leaving the external program with lots of free memory to work with. Or you can precede FNAME with NS: (No Swap) to force Icom to stay in memory. The advantage of the former is that you can run very large external programs, since Icom will free up all the memory it was using, minus just about 200 bytes of code (which it uses to swap itself back in after the program finishes). The advantage of the latter is that it's faster, since no swapping takes place. You can try NS: to avoid a swap first if you like. If you get a "Not enough memory" error trying to run the external program, precede the command with SW: to force a swap. If the executed program displays output to STDOUT (DOS standard output device, as opposed to direct screen writes which most non-command line utilities use), you can have the output redirected to a file or other device such as PRN in the usual manner by following the command with either one or two 'greater than' (>) signs, followed by the name of the file or device you want to redirect TO. Examples: EXEC "UTIL.EXE /parm1 /parm2 > OUTPUT.FIL" EXEC "C:\UTIL\UTIL2.COM *.* /parm1 >>\TEMP\OUTPUT.FIL" Intellicomm v2.01 SCRIPT.DOC 84 The first example redirects output from UTIL.EXE into a file (in the current directory; whatever it happened to be) called OUTPUT.FIL. You could then LIST "OUTPUT.FIL" and view the results, etc. Since only one '>' was specified, if OUTPUT.FIL existed in the current directory, it would be overwritten with the new output. The second example redirects output from C:\UTIL\UTIL2.COM into a file called \TEMP\OUTPUT.FIL. Since two '>>' greater thans were specified, output would be appended (added to the end of) \TEMP\OUTPUT.FIL if it already existed. If you specify a device name to redirect to, do NOT follow the device name with a colon. For example use '> PRN' and not '> PRN:'. Note that these are the only two forms of redirection the EXEC command supports. It does not support pipes (|) or input redirection (<). You must use the DOS command for those. When to use EXEC vs. using the DOS command? EXEC is designed to run only .COM or .EXE programs and it does NOT invoke a copy of the command processor (COMMAND.COM usually) to execute the specified program. This is an important point when you must check the error return code from a program such as a virus checker or the like, since COMMAND.COM (which is what the 'DOS' command uses to run external programs/commands) does *not* return the errorlevel of the program it executes. The advantage of the 'DOS' command is that you can run .BAT files, and can execute internal DOS commands such as COPY, DEL, MKDIR, RMDIR (though using the script equivalents of these commands is faster). The disadvantage of using the DOS command is that you cannot check the error return code (if any) of the program you execute. With the EXEC command, you *can* check the error code returned by the program (see below) but you cannot execute .BAT files or internal DOS commands which require COMMAND.COM. ERRORLEVEL If the program is successfully executed, $ERRORLEVEL is set to the return code of the program (or to a negative value if the program could not be executed). This is similar to the 'ERRORLEVEL' variable you can test from a batch (.BAT) file after executing a program. 1+ Any value above zero is the return code of the program that was executed. Such a value will only be useful if the program's documentation specifically outlines the MEANING of error return codes. Some programs do not return a value, and in those cases it's useless to test for an $ERRORLEVEL above zero. 0 Program successfully loaded and executed. Again, unless a program's documentation specifically states that it sets the DOS errorlevel to zero on successful execution, you should not assume that you'll get a zero return code on successful execution. Some programs just leave errorlevel alone ... in which case it could be set to any (zero or positive) value when the program finishes. You're free to always check for a NEGATIVE $ERRORLEVEL after an EXEC (see below), but only check for zero or greater if you know the program you just EXECed returns an errorlevel. -1 No such file or directory (program not found; remember to specify Intellicomm v2.01 SCRIPT.DOC 85 the full D:\PATH\ to the file if it isn't in a directory on your DOS PATH). Programs never return this errorlevel. It is set by the EXEC command. -2 Too many open files (no file handles). Increase the FILES= in your CONFIG.SYS file, then reboot to remedy the situation. Programs never return this errorlevel. It is set by the EXEC command. -3 Not enough memory to execute the program. You can remedy this one by preceding the command with "SW:" to have Icom swap itself out of memory before executing the external program. Programs never return this errorlevel. It is set by the EXEC command. SEE ALSO DOS EXAMPLE EXEC "SW:C:\UTIL\BIGPROG.EXE /1stparm /2ndparm" if $ERRORLEVEL < 0 ;less than zero? print "Unable to execute BIGPROG.EXE, errorcode: " $ERRORLEVEL else print "BIGPROG.EXE returned errorlevel: " $ERRORLEVEL endif EXIST____________________________________________________________________ SUMMARY EXIST sFILESPEC cCOMMAND DESCRIPTION If sFILESPEC exists, cCOMMAND is executed. If sFILESPEC doesn't exist, cCOMMAND is skipped. sFILESPEC is a file specification (wildcards * and ? are accepted) including an optional drive and path (D:\PATH\*.BAT for example). If you omit the drive (D:) the current drive ($CURDRIVE) is assumed. If both the drive and path are omitted, the current path is assumed ($CURDIR). ERRORLEVEL No errorlevel is necessary. Use cCOMMAND. SEE ALSO DISKFIND, FINDFIRST, FINDNEXT, NOTEXIST EXAMPLE variable filename $HOME_DIR "POSTDOWN.BAT" Intellicomm v2.01 SCRIPT.DOC 86 exist filename edit filename ;edit POSTDOWN.BAT if it exists EXIT_____________________________________________________________________ SUMMARY EXIT [nERRORCODE] DESCRIPTION Exits the script processor. Use EXIT if you have chained to another script (using the SCRIPT command) and you don't wish to return to the original script. nERRORCODE is only valid if Intellicomm is in fully automated mode (i.e. the script must have been called via a job Custom Command/Run Script task). If nERRORCODE is 0 (zero) no action is taken by Intellicomm. If nERRORCODE is 1 or greater, Intellicomm cancels the rest of the job tasks for the CURRENT BBS, and removes the current BBS from the dialing queue. If nERRORCODE is less than zero (-1, -2, etc) Intellicomm aborts all automated jobs. NOTE: If a non-zero nERRORCODE follows the EXIT command, Intellicomm prints a message to the screen stating "Script aborted by EXIT code: nERRORCODE". SEE ALSO SCRIPT, RETURN, SCRTUTOR.DOC section "WHAT HAPPENS WHEN A SCRIPT ENDS?" EXAMPLE waitfor "Some text" 120 major_error ... return major_error: EXIT 1 ;abort all scripts, and the automated job for current BBS as ; well FCLOSE___________________________________________________________________ SUMMARY FCLOSE vHANDLE DESCRIPTION Closes the file vHANDLE. vHANDLE must be a valid file handle stored by the FOPEN command. ERRORLEVEL 0 FCLOSE successful Intellicomm v2.01 SCRIPT.DOC 87 1 FCLOSE unsuccessful (disk error; most likely the disk is full). SEE ALSO FOPEN EXAMPLE FFLUSH___________________________________________________________________ SUMMARY FFLUSH vHANDLE DESCRIPTION Immediately writes any data in vHANDLE's file output buffer to disk. vHANDLE is the variable you used when you FOPENed the file. FPUTS and FPUTC do not write data to disk immediately. They buffer data until an effecient disk write can be made (or until FCLOSE is called). If you have something very important to write to disk, use FFLUSH after FPUTS / FPUTC, etc., to immediately write the data to disk. If the computer locks up, or the power goes out while data is waiting to be written to disk in the file output buffer, the data will be lost. NOTE 1: FFLUSH is automatically called when you FCLOSE a file. NOTE 2: Disk cache programs (such as DOS's SMARTDrive) also buffer data in memory, for more effecient disk writes. FFLUSH cannot force a disk cache to write data to disk, so if a disk cache with a write-behind buffer is operating, FFLUSH has no effect. This is not a limitation of Icom's script language, or even a limitation of DOS: it's a limitation of using disk cache write-behind buffers. They write data on their own time, and I have yet to figure out how to force any disk cache to write its data to disk, if indeed there is any way (aside from executing non- standard and slow commands at the DOS prompt). If anyone knows the secret, feel free to pass it along, as I'd like to have FFLUSH force disk cache programs to write to disk as well. ERRORLEVEL 0 Disk write (FLUSH) was successful. 1 Disk write unsuccessful (the disk is likely full). SEE ALSO FOPEN, FCLOSE EXAMPLE FGETC____________________________________________________________________ SUMMARY Intellicomm v2.01 SCRIPT.DOC 88 FGETC vBUFFER vHANDLE DESCRIPTION Gets a single character from file vHANDLE (a valid file handle variable as stored by FOPEN) and stores the character in variable vBUFFER. Also increments the file pointer by one character (multiple calls to FGETC go through a file character by character). ERRORLEVEL 0 FGETC successful (a character was stored in vBUFFER). 1 End of file (vBUFFER contains -1). SEE ALSO FGETS EXAMPLE variable fh variable buf fopen fh "TEST.DAT" "r" ;open TEST.DAT for reading while 1 ;loop until BREAK FGETC buf fh if $errorlevel = 1 break ;end of file printnc buf endwhile fclose fh FGETS____________________________________________________________________ SUMMARY FGETS vBUFFER vHANDLE DESCRIPTION Gets a line of characters from file vHANDLE (a valid file handle variable as stored by FOPEN) and stores the characters in variable vBUFFER. Also increments the file pointer by the number of characters read (multiple calls to FGETS go through a file line by line). FGETS stops reading when a line feed character is encountered, 256 characters (the maximum number of characters that can be stored in a script variable) have been read, or the end of the file is encountered. In text files, carriage return / line feed pairs end each line. FPUTS also writes a carriage return / line feed after the line of data written. NOTE: The carriage return / line feed pair at the end of each line are stripped by FGETS, since you will rarely want them. Intellicomm v2.01 SCRIPT.DOC 89 ERRORLEVEL 0 FGETS successful (characters were stored in vBUFFER). 1 End of file (vBUFFER is empty). It's possible for vBUFFER to be empty after FGETS, but to not have an end of file condition ($ERRORLEVEL 1). Blank lines in text files will result in an empty vBUFFER, but $ERRORLEVEL will *not* be set to 1 until the end of the file is reached. SEE ALSO FGETC EXAMPLE variable fh variable buf fopen fh "TEST.DAT" "r" ;open TEST.DAT for reading while 1 ;loop until BREAK FGETS buf fh if $errorlevel = 1 break ;end of file printnc buf endwhile fclose fh FILEMAN__________________________________________________________________ SUMMARY FILEMAN [sDRIVEDIR] [sFILESPEC] DESCRIPTION Enters Icom's internal File Manager (same as pressing [Alt-F] from most places in Intellicomm). sDRIVEDIR is an optional drive and directory (D:\PATH) to display. If omitted, $CUR_DIR is assumed. sFILESPEC is an optional filespec to display (wildcards ? and * are accepted). If omitted, *.* is assumed. EXAMPLE FILEMAN $HOME_DIR "*.*" ;display all files in the \ICOM directory FILESIZE_________________________________________________________________ SUMMARY FILESIZE vBUFFER [sFILENAME] DESCRIPTION Stores the size (in bytes) of file sFILENAME in variable vBUFFER. If Intellicomm v2.01 SCRIPT.DOC 90 sFILESPEC is omitted, the last file found with EXIST, FINDFIRST, or FINDNEXT is assumed. sFILENAME can be a full D:\PATH\FILENAME.EXT (drive, path, filename, extension). If you omit either the drive or the path, the current drive/directory is assumed. ERRORLEVEL There's no need to check $ERRORLEVEL after FILESIZE. If the file doesn't exist, vBUFFER will contain -1 (minus one). SEE ALSO FINDFIRST, FINDNEXT, $FSIZE FINDFIRST________________________________________________________________ SUMMARY FINDFIRST vBUFFER sFILESPEC [nATTRIBUTES] DESCRIPTION FINDFIRST is used to check for the existence of files (including hidden files and system files), directories, and/or disk labels. vBUFFER is a variable where FINDFIRST will store the name of the first matching file or directory name. sFILESPEC is the file specification to search for (wildcards ? and * are accepted), and it may contain an optional drive and path (D:\PATH). Examples: "C:\ICOM\*.*", "\ICOM\SCR\POST????.SCR", etc). If the drive is omitted, the current drive is assumed ($CUR_DRIVE). If the path is omitted the current directory is assumed. The filename portion MUST be specified. *.* is not assumed if you specify a D:\PATH but omit a filespec. nATTRIBUTES allows you to specify file attributes that the file much match in order to be found by FINDFIRST. If nATTRIBUTES is omitted, 0 (normal and read only files) is assumed. To specify nATTRIBUTES, select one or more attributes from the list below: 0 Normal and read only files 2 Hidden files 4 System files 8 Disk volume label 16 Subdirectories ...and ADD the numbers up. For example, to find normal files, hidden files, and subdirectories, add 0 (not necessary really; 0 is useless when adding), 2 (Hidden files) and 16 (Subdirectories) together (0 + 2 + 16 = 18) and specify 18 as the nATTRIBUTES parameter. NOTE: If FINDFIRST locates a file, directory or volume label, it stores the FILENAME.EXT in vBUFFER, and also sets the $FXXXX variables listed in the "SEE ALSO" section below. The $FXXXX variables allow you to Intellicomm v2.01 SCRIPT.DOC 91 check the date, time, and attributes of the item that FINDFIRST located. ERRORLEVEL 0 FINDFIRST successful (a matching item was found and its name has been stored in vBUFFER). 1 FINDFIRST unsuccessful (nothing found matching sFILESPEC with the specified nATTRIBUTES). SEE ALSO EXIST, FINDNEXT, NOTEXIST, $FARCH, $FDATE, $FDAY, $FHIDDEN, $FHOUR, $FMIN, $FMONTH, $FRDONLY, $FSEC, $FSIZE, $FSUBDIR, $FSYSTEM, $FTIME, $FVOLID, $FYEAR EXAMPLE ;simulates a regular 'DIR' command from DOS, but shows Hidden and ; System files/subdirectories as well variable buf FINDFIRST buf "C:\*.*" 8 ;get the disk volume label (always in root ; directory) print "The volume in drive C: is " buf print FINDFIRST buf "C:\*.*" 22 ;all attributes except volume label while $ERRORLEVEL = 0 ;end loop when no more files strpad buf " " 15 ;pad with spaces to a length of 15 printnc buf if $FSUBDIR = "+" ;is it a subdirectory? printnc "<DIR> " else assign buf $FSIZE ;get the filesize strpadl buf " " 15 ;pad left side with spaces to 15 chars printnc buf endif printnc " " $FDATE print " " $FTIME findnext buf ;also sets $ERRORLEVEL = 1 if no more files endwhile FINDNEXT_________________________________________________________________ SUMMARY FINDNEXT vBUFFER DESCRIPTION Finds the next matching file after using FINDFIRST, and (if any more files exist) stores the name of the item in variable vBUFFER. FINDNEXT Intellicomm v2.01 SCRIPT.DOC 92 is only of use when wildcards (* or ?) were used in the original FINDFIRST 'sFILESPEC' parameter. For example, this is useless: findfirst buf "c:\icom\icom.exe" FINDNEXT buf ;can't possible have another file called ICOM.EXE This isn't: findfirst buf "c:\icom\icom.*" ;any extension will do, so you could ; match ICOM.EXE, ICOM.PWD, ICOM.HLP, ; ICOM.DAT, etc. FINDNEXT buf ;this is likely to find another file ; matching ICOM.* NOTE 1: The attributes (nATTRIBUTES) parameter specified in the original FINDFIRST also apply to FINDNEXT. So if you were searching for Subdirectories in the original FINDFIRST, FINDNEXT would only find Subdirectories. NOTE 2: The $FXXXX variables listed in the 'SEE ALSO' section of FINDFIRST are also set by FINDNEXT. See FINDFIRST for details. ERRORLEVEL 0 FINDNEXT successful (the name of the item was stored in vBUFFER). 1 FINDNEXT unsuccessful (nothing else was found). SEE ALSO FINDFIRST EXAMPLE ;display all .BAT files in the \ICOM directory variable buf findfirst buf "\ICOM\*.BAT" while $ERRORLEVEL = 0 print buf FINDNEXT buf endwhile FNSTRIP__________________________________________________________________ SUMMARY FNSTRIP vBUFFER sFILESPEC nMODE DESCRIPTION Gets portions of sFILESPEC according to nMODE and stores the result in vBUFFER. Intellicomm v2.01 SCRIPT.DOC 93 Values for nMODE: 0 Full filename 1 All except the drive 2 D:NAME.EXT Drive, name, extension 3 NAME.EXT Name and extension 4 D:\PATH\NAME Drive, path, and name (no extension) 5 \PATH\NAME Path and name (no extension) 6 D:NAME Drive and name (no extension) 7 NAME Name only (no extension) 12 D:\PATH\ Drive and path only 13 \PATH\ Path only 14 D: Drive only 15 .EXT Extension only EXAMPLE variable drive_path FNSTRIP drive_path "D:\PATH\FILENAME.EXT" 12 print drive_path ;this prints D:\PATH\ FOPEN____________________________________________________________________ SUMMARY FOPEN vHANDLEBUF sFILENAME sMODE DESCRIPTION NOTE: Before using FOPEN, please read the section "PERMANENT VARIABLES: INTRODUCTION TO FILE INPUT/OUTPUT" in SCRTUTOR.DOC. Opens file sFILENAME for reading/writing or both (as specified by sMODE) and stores a file 'handle' in variable vHANDLEBUF. vHANDLEBUF should be a variable defined with the script VARIABLE command. vHANDLEBUF is used to distinguish one open file from another ( must then be used by various other file-related commands, to manipulate the open file. sFILENAME is the name of the file to open. A drive and path can (and should) be specified along with the filename. Wildcards (? and *) are NOT accepted by FOPEN. sMODE must be one of the following values: "r" Opens sFILENAME for Reading (no writes are allowed: the file cannot be modified). "w" Opens sFILENAME for Writing. If the file exists, its contents will be destroyed. No reads are allowed in this mode. "a" Opens sFILENAME for Appending (no reads are allowed; data is added to the end of the file). If the file does not exist, it will be created. Intellicomm v2.01 SCRIPT.DOC 94 Advanced (open for reading AND writing): "r+" Opens sFILENAME for Reading and writing. If sFILENAME does not exist, it will be created. "w+" Opens sFILENAME for Writing and reading. If sFILENAME exists, its contents are destroyed (use "r+" to open for read/write without destroying existing files). "a+" Opens sFILENAME for reading and Appending (adds to the end). If the file doesn't exist, it will be created. NOTE 1: Never open the same file twice. For example, you can open the capture file to add some data to it, but you must first call CAPCLOSE to close the file: variable f cappush ;save capture status/filename capclose FOPEN f $CAP_NAME "a" fputs f "^M^JAdd something to the capture file...^M^J" fclose f cappop ;reset the capture file to its original state You 'can' get away with opening the same file multiple times on some computers, but if SHARE is loaded the user will receive an error message and the FOPEN will not succeed. Exception 12 and 13 errors (which effectively hang the machine, requiring a re-boot) can also result from operating on an open file. NOTE 2: Never attempt to DELETE or RENAME an open file. It will result in lost chains, and even exception 13's. NOTE 3: Most of the file-oriented commands such as COPY, APPEND, etc., perform their own FOPEN. Don't attempt to use a file-oriented command on an open file (FINDFIRST/FINDNEXT/EXIST/NOTEXIT are fine, but most others can cause SHARE or exception errors if used on an open file). NOTE 4: Most Intellicomm data files (.BAT, .BIF, .INI, .KWD, .SCR [even the currently executing script]) are CLOSED when scripts are running. Exceptions are the capture file ($CAP_NAME, which can be closed with CAPCLOSE), any files you've previously opened with FOPEN (which can be closed with FCLOSE), and any catalogs you've opened with COPEN (which opens *5* files: the .DBF, .DBT, and the 3 .NDX files related to the catalog. Catalogs can be closed with CCLOSE). You can safely FOPEN any other Intellicomm data files, if you know what you're doing and have a specific need to use a data file directly. When Intellicomm needs information from a data file it normally opens the file, takes what it needs, and closes it immediately. This is true even while scripts are running: LOADBIF, for example, does not leave the .BIF open. It simply loads the information into memory, and the .BIF file itself is closed when LOADBIF finishes. NOTE 5: Never write to ICOM.USE (the Usage Log) unless you've read the Intellicomm v2.01 SCRIPT.DOC 95 Call Data Standard specifications (available on many BBS's as CDS.ZIP). Icom's Usage Log follows a fixed format, and writing anything other than comments to the file (which should be done with the STAMP command and not with FOPEN/FPUTS/FCLOSE) could render the entire Usage Log unreadable. ERRORLEVEL 0 sFILENAME successfully opened. 1 sFILENAME doesn't exist (read mode) or couldn't be created (invalid drive, path or filename in write mode, or root directory full). 2 Too many open files. Tell the user to increase the FILES= line in the computer's CONFIG.SYS file. 3 Not enough memory to open the file. 4 Permission denied (tried to open a read-only file in Write mode). 5 Miscellaneous errors too numerous and obscure to mention. The file wasn't opened. NOTE: If you get anything other than $ERRORLEVEL = 0 after FOPEN, do not attempt to use vHANDLEBUF. This bit below would abort with an "Invalid file handle" error: variable f FOPEN f "|INVALID" "w" ; '|' is not valid in DOS filenames if $ERRORLEVEL > 0 fclose f ;aborts the script. The file is NEVER opened endif ; if an $errorlevel is returned, and the value ; stored in variable 'f' will be 0 (zero) which ; is always an invalid file handle. SEE ALSO APPEND, APPENDS, APPENDSNC (quicker ways to add to a file without bothering with FOPEN/FCLOSE), FCLOSE EXAMPLE 1 variable datfile FOPEN datfile "TEMP.$$$" "w" fputs datfile "Store this on line 1 of TEMP.$$$" fputs datfile "Store this on line 2 of TEMP.$$$" fclose datfile EXAMPLE 2 variable key variable f msgopen "Please turn on your printer and press a key..." inkey key msgclose fopen f $PRN "w" ;open the printer device for writing Intellicomm v2.01 SCRIPT.DOC 96 fputs f "These lines will be printed on the printer." fputs f "Most printers require a CR before they actually print anything" fputs f "but FPUTS sends a CR so that's no problem. If you use FPUTC" fputs f "or FPUTSNC (no CR) then your line will not be printed until" fputs f "you send a CR." fputs f "^L" ;Ctrl-L is a Form Feed. It causes the printer to move to ; the top of the next page. fclose f FPUTC____________________________________________________________________ SUMMARY FPUTC vHANDLE sCHARACTER DESCRIPTION Writes the character sCHARACTER to the file handle specified by vHANDLE. vHANDLE must be a file handle obtained via FOPEN. No carriage return or line feed is added after sCHARACTER (as with FPUTS). ERRORLEVEL 0 sCHARACTER was successfully written. 1 Unable to write sCHARACTER (the disk is likely full). SEE ALSO FPUTS, FPUTSNC EXAMPLE FPUTS____________________________________________________________________ SUMMARY FPUTS vHANDLE sSTRING ... DESCRIPTION Writes sSTRING to the file signified by vHANDLE. A carriage return and line feed are automatically added to the end of sSTRING (terminating the line in the file). Use FPUTSNC if you don't want CR/LF added. vHANDLE must be a valid file handle obtained via FOPEN. ERRORLEVEL 0 sSTRING was successfully written. 1 Unable to write sSTRING (the disk is likely full). SEE ALSO FPUTC, FPUTSNC Intellicomm v2.01 SCRIPT.DOC 97 EXAMPLE variable datfile fopen datfile "TEMP.$$$" "w" FPUTS datfile "Store this on line 1 of TEMP.$$$" FPUTS datfile "Store this on line 2 of TEMP.$$$" fclose datfile FPUTSNC__________________________________________________________________ SUMMARY FPUTSNC vHANDLE sSTRING ... DESCRIPTION Writes sSTRING to the file signified by vHANDLE. A carriage return and line feed are NOT automatically added to the end of sSTRING (as with FPUTS). Use FPUTS if you want to terminate the line with CR/LF. vHANDLE must be a valid file handle obtained via FOPEN. ERRORLEVEL 0 sSTRING was successfully written. 1 Unable to write sSTRING (the disk is likely full). SEE ALSO FPUTC, FPUTS EXAMPLE variable datfile fopen datfile "TEMP.$$$" "w" FPUTS datfile "Store this on line 1 of TEMP.$$$" FPUTS datfile "Store this on line 2 of TEMP.$$$" fclose datfile FSEEK____________________________________________________________________ SUMMARY FSEEK vHANDLE nOFFSET nORIGIN DESCRIPTION FSEEK is an advanced command that moves the file pointer of the file signified by vHANDLE. The file pointer determines whether the next read/write will take place, as outlined in "INTRODUCTION TO FILE INPUT/OUTPUT" section of SCRTUTOR.DOC. vHANDLE is a valid file handle obtained by FOPEN. Intellicomm v2.01 SCRIPT.DOC 98 nOFFSET is the number of bytes to seek from nORIGIN (0 = the first byte in the file). Positive numbers seek forward from nORIGIN, negative numbers seek backwards from nORIGIN. nORIGIN is a number that specifies the initial location of the seek: 0 = From the beginning of the file. 1 = From the current position of the file pointer. 2 = From the end of the file. NOTE: It is legal to seek past the end of a file, but you cannot seek past the beginning of a file. If you seek past the end of a file, the portion of the file from the original end-of-file to the new FSEEK position will likely contain garbage. Assume a file called HELLO, with 5 bytes in it: HELLO If you did this to modify HELLO in your script: variable f fopen f "HELLO" "r+" ;open for read/write FSEEK f 10 0 ;seek 10 bytes from the beginning (past the end) fputs f "THERE" fclose f ...the file HELLO would likely contain garbage between "HELLO" (the original file contents) and "THERE" (the portion added at position 10 in the above example): 1 012345678901234 <-- Numeric ruler for reference HELLO%~@-\THERE <-- Contents of file HELLO after FSEEK 10 0/FPUTS ERRORLEVEL 0 FSEEK was successful (the file pointer has been moved). 1 FSEEK was unsuccessful (the file pointer remains where it was previously). This error will occur if you attempt to seek past the beginning of the file ('FSEEK f -100 2' to seek back 100 bytes from the END of the file, on a file that is only 50 bytes long for example). SEE ALSO FOPEN EXAMPLE Please see "PERMANENT VARIABLES: INTRODUCTION TO FILE INPUT / OUTPUT" in SCRTUTOR.DOC for detailed FSEEK explanations and examples. variable fh Intellicomm v2.01 SCRIPT.DOC 99 fopen fh "TEST.$$$" "r+" FSEEK fh 100 0 fputs fh "TEST" fclose f FTELL____________________________________________________________________ SUMMARY FTELL vBUFFER vHANDLE DESCRIPTION Gets the current position of the file pointer for file vHANDLE and stores it in vBUFFER. vHANDLE must be a valid file handle obtained via FOPEN. EXAMPLE variable fh variable buf fopen fh "TEST.FIL" "r" fgets buf fh FTELL buf fh print "Current positon: " buf GETENV___________________________________________________________________ SUMMARY GETENV vBUFFER sENVLABEL DESCRIPTION Gets the contents of envirnment variable sENVLABEL and if found, stores it in vBUFFER. ERRORLEVEL 0 Label sENVLABEL was found in the environment and its contents has been stored in vBUFFER. 1 Label sENVLABEL does not exist in the environment. SEE ALSO SETENV EXAMPLE variable path GETENV path "PATH" Intellicomm v2.01 SCRIPT.DOC 100 print "PATH=" path GETFNAME_________________________________________________________________ SUMMARY GETFNAME [sDIRECTORY] [sFILESPEC] [sHELPLINE] DESCRIPTION This command requires a few skills to use, but it can be very useful in advanced script projects. GETFNAME accesses a variation of the Icom "File Manager" (FILEMAN command) displaying all files that match sDIRECTORY sFILESPEC (a D:\PATH\FILESPEC the drive, path, AND filespec are all optional) as the File Manager does. But GETFNAME allows the user to "Select" one or more files for your script to operate on. Note that D:\PATH\ and FILESPEC are specified *separately* in different parameters. If you omit the 'D:' (Drive) in sDIRECTORY, the current drive is assumed If you omit the \PATH\ portion, the \ICOM directory, or the last directory displayed is assumed (a trailing slash is not necessary when specifying path names, but is acceptable). If you omit the FILESPEC, *.* is assumed. Thus if you use: GETFNAME "\" D:\*.* (where D: is the current drive) is displayed to the user. As in the Icom File Manager, the user can change to a new directory if need be, and can also View, Edit, Find (full disk search), Ren/Move, Delete files, etc., before making a selection. If sHELPLINE is specified, it is displayed in the File Manager message box, until the user presses a key. Note that if you omit the sFILESPEC parameter but DO want to specify a help line, you must do the following: GETFNAME "\" "" "Help Line" ;<-- Help must be the THIRD parameter Since the user is able to "Tag" and "Select" multiple files, GETFNAME does not store the selected filename(s) in a script variable, but instead writes all the selected files out to a text file called \ICOM\GETFNAME.LST, which you can read using the script File I/O commands (see the example below). For example, if you displayed C:\ICOM\*.BAT with GETFNAME, and the user Tagged/Selected the files: POSTMAIL.BAT and POSTDOWN.BAT, the file \ICOM\GETFNAME.LST would contain the following two lines: C:\ICOM\POSTMAIL.BAT C:\ICOM\POSTDOWN.BAT ERRORLEVEL GETFNAME does not set $ERRORLEVEL. On entry it deletes the file C:\ICOM\GETFNAME.LST if it exists, and thus if the user doesn't select Intellicomm v2.01 SCRIPT.DOC 101 any files, GETFNAME.LST will not exist. This is how you can determine whether the user selected any files or not: by the existence or non- existence of GETFNAME.LST after GETFNAME finishes (see example below). SEE ALSO DIRFIND, DISKFIND, LOCATEFILE EXAMPLE ;NOTE that this example is only meant to illustrate the GETFNAME command ; and you could accomplish much the same thing by using a single UPLOAD ; command, without specifying the filenames to upload. When this is the ; case, UPLOAD prompts the user to enter filenames just as when you ; press [PgUp] when online, and the user could also press [Alt-F] to ; enter the Upload File Picker (which does the same thing as below). variable lstname $HOME_DIR "GETFNAME.LST" ;C:\ICOM\GETFNAME.LST variable lst ;file handle for GETFNAME.LST variable s ;general purpose stritem s $UL_PATH 1 ;store 1st dir on U/L PATH in s GETFNAME s "" "Please ^"Select^" one or more files to upload" notexist lstname goto skip_ul strins lstname "@" 0 1 ;@C:\ICOM\GETFNAME.LST upload "Z" lstname ;uploads all files on the list strdel lstname 0 1 ;kill the @ (position 0, 1 char) ;This below illustrates how to extract each filename separately from ; GETFNAME.LST. We only PRINT the filenames below (which are stored ; in 's' by FGETS), but you'd be free to do whatever you wanted with ; the filename(s), including FOPENing the file, DELETEing it, etc. if $ERRORLEVEL = 0 ;set by UPLOAD if successful print "Files uploaded:" fopen lst lstname "r" ;open GETFNAME.LST for "r"eading while 1 ;endless loop (until BREAK) fgets s lst ;get first/next line from GETFNAME.LST if $ERRORLEVEL <> 0 BREAK ;exit loop at end of file (set by FGETS) print s ;do whatever you like with each file endwhile fclose lst ;always close what you FOPEN endif delete lstname ;not necessary, but nice to keep it clean skip_ul: return GETS_____________________________________________________________________ GETSXY___________________________________________________________________ Intellicomm v2.01 SCRIPT.DOC 102 SUMMARY GETS vINPUT nMAXLEN GETSXY vINPUT nMAXLEN [nX] [nY] [nCOLOR] DESCRIPTION Both commands get user input from the keyboard, a maximum of nMAXLEN characters long, and store the result in variable vINPUT. If variable vINPUT contains any data, it is offered to the user as a default value. I.e. if you do not wish to offer a default, you must clear the vINPUT variable if it was used previously: assign myvariable "" ;clear variable 'myvariable' GETS myvariable 10 ;get up to 10 characters of input GETS obtains the input at the current cursor position ($SCRN_Y, $SCRN_Y), while GETSXY obtains input at specific screen X,Y coordinates (nX, nY parameters above). Both nX and nY are optional and if both coordinates are omitted, the input is obtained at the current cursor position (as with GETS). If only the nX (screen column, left to right) position is specified, $SCRN_Y (the current cursor row) is used. Both commands get input and display the input 'field' in a specific color, showing the maximum length (nMAXLEN) of the input field. GETS uses the $BAR_COLOR color (as with most Intellicomm input fields) as does GETSXY if the [nCOLOR] parameter is omitted. If you specify [nCOLOR] with GETSXY (or if you temporarily change $BAR_COLOR prior to using either GETS or GETSXY), you can display an input field using another color. See the COLOR CODES Appendix for information on creating custom color codes. GETS and GETSXY use the same input routine that BOXGETS uses, but they don't display a box or prompt (>) character. Please see the BOXGETS description for more details on cursor keys and hotkeys available to the user when entering input, and an example of checking $ERRORLEVEL after the user input (Esc key pressed, etc). ERRORLEVEL 0 The user entered something then pressed the [Enter] key or left mouse button (variable vINPUT contains data). 1 The user pressed [Enter], but variable vINPUT is empty ... nothing was entered. 2 The user pressed the [Esc] key or right mouse button to cancel. If this occurs, the contents of vINPUT reverts to its original value (the default you offered) whether the user changed it on the input line or not. 256+ If a value of 256 or greater is in $ERRORLEVEL when BOXGETS returns, the user pressed a key defined in one of the $HOTKEY_? variables. See the BOXGETS example for details. SEE ALSO Intellicomm v2.01 SCRIPT.DOC 103 BOXGETS, INKEY EXAMPLE variable myvariable ;define a variable called 'myvariable' assign myvariable "Default Response" ;give the user a default printnc "Enter your response: " ;print, no CR GETS myvariable 30 ;30 chars max printnc "You entered: " print myvariable ;this bit below gets user input on the status line (similar to the ; way Icom prompts for a new capture file when you press [Alt-L]) assign $STAT_ON 0 ;turn the status line off scroll 1 $SCRN_HEIGHT $SCRN_WIDTH $SCRN_HEIGHT 0 $STAT_COLOR ;draws a blank line in the usual status bar color, on the bottom ; screen line printraw 1 $SCRN_HEIGHT $STAT_COLOR "Enter your response:" GETSXY myvariable 80 22 $SCRN_HEIGHT $STAT_COLOR ;on the status line assign $STAT_ON 1 ;restore status line GOSUB____________________________________________________________________ RETURN___________________________________________________________________ SUMMARY GOSUB LABEL DESCRIPTION GOSUB/RETURN work as a team and allow you to execute a set of script commands, then continue where you came from. While GOTO simply jumps to a label without returning, GOSUB jumps to the label, then RETURNs to the command(s) following the GOSUB, if any. One exception is when GOSUB is used in a WHEN command. In that case, control returns to the WAITFOR if/when a RETURN is found (see the example below). NOTE: If Icom runs across a RETURN command and has not previously executed a GOSUB command, the script simply ends at that point (RETURN is the usual command to exit a script). NOTE FOR ADVANCED SCRIPT WRITERS: GOSUB can also jump to a label using a variable. Just store the label's name in the variable, then specify the variable preceded by an asterisk: variable label "some_label" gosub *label ;same as 'gosub some_label' some_label: Intellicomm v2.01 SCRIPT.DOC 104 SEE ALSO GOTO EXAMPLE GOSUB initialize_script ;jump to label 'initialize_script:' ;control returns to this line after the RETURN send "Some Command" waitfor main_menu 120 when when "some prompt" gosub handle_some_prompt when "another prompt" "do this" waitfor main_menu 120 ;control returns to WAITFOR after the GOSUB RETURN ;exit script (no GOSUB is active) initialize_script: ;subroutine labels are the same as GOTO labels ;define a variable for use later in the script variable main_menu getbif main_menu "L" "mnap" ;BIF [L]ogon section, Main Menu A prompt RETURN ;return from the subroutine handle_some_prompt: ... ;any number of commands can be placed here to handle what needs doing RETURN GOTO_____________________________________________________________________ SUMMARY GOTO LABEL DESCRIPTION Jumps to the label specified by LABEL (a colon is not needed after LABEL, but is acceptable). GOTO is used to skip over a portion of a script when a certain condition warrants it. Script labels are covered in the introduction of SCRTUTOR.DOC. NOTE FOR ADVANCED SCRIPT WRITERS: GOTO can also jump to a label using a variable. Just store the label's name in the variable, then specify the variable preceded by an asterisk: variable label "some_label" goto *label ;same as 'goto some_label' some_label: Intellicomm v2.01 SCRIPT.DOC 105 SEE ALSO GOSUB EXAMPLE online GOTO skip_logon ;skip dial/logon if have a connection dial "Favorite BBS" 1 waitfor "name:" send "Joe Smith" ...etc. skip_logon: send "D SOMEFILE.ZIP Z" download "" hangup return GOTOXY___________________________________________________________________ SUMMARY GOTOXY nX nY DESCRIPTION Moves the cursor to screen column nX (left to right), row nY (top to bottom). The top left corner of the screen is 1 1. If WINDOW or WNDOPEN are currently in effect, the top corner of the WINDOW ($WND_LEFT, $WND_TOP) represents screen coordinate 1 1, instead of the actual top of the video display. SEE ALSO CURPUSH, CURPOP EXAMPLE GOTOXY 1 1 print "This is displayed at the top of the screen, or the top of the" print "current WINDOW (if any)." HANGUP___________________________________________________________________ SUMMARY HANGUP DESCRIPTION Causes the modem to disconnect. If the main setup item "Drop DTR to Intellicomm v2.01 SCRIPT.DOC 106 Hangup?" (*dtrhangup) is set to Yes, HANGUP drops the DTR (Data Terminal Ready) line for 1.5 seconds, delays for 0.5 seconds, then checks the carrier status. If still connected (or if "Drop DTR to Hangup" was set to No) the main setup "Modem Hangup String" (normally +++ATH0) is then sent to the modem. Note that HANGUP ignores the main setup "Confirm Hangup?" option which asks the user for confirmation before hanging up. You can easily simulate your own 'Hangup? Yes No' menu with these commands: IF *hconfirm = 0 ;Confirm Hangup variable set to NO (0)? HANGUP ELSE MENUDEFINE "~Yes" "~No" ;define a Yes/No menu MENUBOXH "" "^IHangup?" ;^I (TAB) puts help on same line as menu IF $ERRORLEVEL = 1 HANGUP ;if "Yes" (item 1) then hang up ENDIF This gives the exact same menu in a box that the main setup "Confirm Hangup?" option does. ERRORLEVEL 0 Successful (disconnected). 1 Unsuccessful (modem reports still connected). Note that if the modem is forcing the carrier detect signal on, HANGUP will always set $ERRORLEVEL 1 and will display a "Hangup Failed" message. HANGUP checks the carrier detect before returning and if it's being forced on, Icom will always think it's connected (it has no other way of knowing, other than what the modem tells it). This problem is quite common due to the way modems are configured from the factory, and the usual fixes are outlined in the "Common Questions & Answers" online help link. HELP_____________________________________________________________________ SUMMARY HELP [sHELPLINK] DESCRIPTION If sHELPLINK is omitted the Help Index is displayed. If sHELPLINK is specified, all .HLP files are searched for the link and, if found, the topic is displayed. Specify sHELPLINK exactly as you see it in the online help system (see example). ERRORLEVEL 0 sHELPLINK was found and displayed 1 sHELPLINK not found SEE ALSO Intellicomm v2.01 SCRIPT.DOC 107 HELPFIND EXAMPLE HELP "Script Language" ;display the Script Language link HELPFIND_________________________________________________________________ SUMMARY HELPFIND sSEARCHTEXT DESCRIPTION Similar to pressing [Ctrl-F1] (Search) in the help system. Searches all help topics for the text sSEARCHTEXT, writes all links containing the text to the file SEARCH.HLP, then displays the file SEARCH.HLP (all the links found, if any) for selection/viewing. ERRORLEVEL 0 sSEARCHTEXT was found and SEARCH.HLP was displayed. 1 sSEARCHTEXT was not found. SEE ALSO HELP EXAMPLE HELPFIND "script" ;find all topics containing the word 'script' ; and display them ;Later in your script you can display the results of the previous ; HELPFIND by using: HELP "Search Results" IF_____________________________________________________________________ ELSE__________________________________________________________________ ENDIF_________________________________________________________________ SUMMARY IF ITEM1 OPERATOR ITEM2 [cCOMMAND] [cCOMMAND] ... [ELSE] [cCOMMAND] ... [ENDIF] DESCRIPTION Intellicomm v2.01 SCRIPT.DOC 108 IF compares ITEM1 and ITEM2 according to OPERATOR and if the comparison is true it executes the cCOMMAND parameter on the same line as the IF command (if specified), or skips cCOMMAND if the comparison is false. If a cCOMMAND parameter is given on the same line as the IF statement, you *cannot* use ELSE or ENDIF. If no cCOMMAND is given on the same line as the IF command, an IF/ENDIF sequence is assumed and the ENDIF becomes mandatory. IF/ENDIF is used to execute a SET of commands (as opposed to a single command) and this sequence either: - executes the command(s) (if any) between IF and ELSE if the comparison is true. OR (ELSE) - executes the command(s) between ELSE (if specified) and ENDIF if the comparison is FALSE. If no ELSE is specified, and the condition is false, control is passed to the script command following the ENDIF. The square brackets in the summary denote OPTIONAL items, and should not be used in your script. ENDIF is only optional if the cCOMMAND parameter is specified on the same line as the IF. The '...' simply means that more of the same (more commands) can follow. The OPERATOR parameter can be one of the following: OPERATOR MEANING --------------------------------------------------------------------- = Equal to <> Not equal to < Less than <= Less than or equal to > Greater than >= Greater than or equal to (=> is not valid) If you plan to use variables with IF, only ITEM1 and/or ITEM2 can be variables. For example, you cannot assign "<>" (Not equal to) to a variable and specify the variable as the OPERATOR parameter. Nor could you assign the word "PRINT" to a variable and specify that variable as the cCOMMAND paremeter. You CAN specify another IF as the cCOMMAND parameter: IF myvariable >= 1 IF myvariable <= 10 PRINT ">= 1 and <= 10" If both ITEM1 and ITEM2 are numbers (variables or contants containing only characters from 0-9 ... surrounding quotes "" or '' are ignored) then a numeric comparison is performed and 1000 is greater than (>) 999, 1 is less than (<) 2 as you'd expect. If either ITEM1 or ITEM2 contain TEXT (characters other than 0-9) then a text or "ASCII" comparison is performed. Text comparisons use the ASCII codes of each character, as outlined in the ASCII CODES Appendix. One string will be 'greater than' another string if it contains a character with a higher ASCII code. "B" is greater than "A", and "C" is greater than "B", "Yes" (which starts with a "Y") is greater than "No" (which Intellicomm v2.01 SCRIPT.DOC 109 starts with a "N"), etc. The ASCII codes assign numbers to all the characters, and these numbers go in the order you'd expect when comparing alphabetic characters. According to ASCII though, lowercase text is *greater than* UPPERCASE text. If you compared "Icom" and "ICOM" ... "Icom" would be greater due to the lowercase "c". The ASCII CODES Appendix shows you the numeric ASCII equivalent of each character so you can see which characters are greater than or less than others. Text comparisons won't be used with IF in a greater than/less than situation very often. You'll normally want to see if one piece of text (perhaps something the user entered via the GETS command) is EQUAL TO (=) or NOT EQUAL TO (<> ... greater than or less than) some other text. In order for your comparisons to be accurate, however, you must make sure you're comparing text that is the same case (both strings uppercase, or both lowercase). The STRUPPER and STRLOWER commands convert text to uppercase/lowercase mainly for this purpose. If you get confused about whether to use < or > for greater than/less just think of them as arrows. Greater than (>) points to the right ... there are a 'greater' number of right-handed people than there are left- handed people. So >, which points towards your RIGHT hand is GREATER THAN. NOTE: You needn't indent the commands as was done above in the summary. Indenting simply make the script more understandable, and also helps you to see that something is MISSING if you forget the ENDIF. ENDIF is mandatory when IF is used, and your script will abort with an 'IF without ENDIF' error if you forget the ENDIF. TIP: You can use the IF/ENDIF sequence on its own, OR with any script command that accepts another cCOMMAND as its parameter (EXIST, NOTEXIST, OFFLINE, ONLINE, WHEN, etc). ERRORLEVEL IF does not change $ERRORLEVEL. The decision-making logic is built into the command. SEE ALSO WHILE/ENDWHILE EXAMPLE 1 MENUDEFINE "~Yes" "~No" MENUBOXV "DELETING SOMEFILE.TXT" "Are you sure you want to do this?" ;MENUBOXV sets $ERRORLEVEL according to what the user selected. ; If $ERRORLEVEL = 1, the user selected "Yes" (menu item 1). See the ; MENUBOXV summary for details. IF $ERRORLEVEL = 1 DELETE "SOMEFILE.TXT" variable Dog1 "DOG" Intellicomm v2.01 SCRIPT.DOC 110 variable Dog2 "Dog" strupper Dog2 ;convert "Dog" to "DOG" (all uppercase) IF Dog1 = Dog2 print "Dog1 and Dog2 are both the same." ;without the strupper to convert "Dog" (what Dog2 is initially ;assigned) to "DOG", the above would NOT be printed. assign Dog2 "CAT" ;put the word CAT in 'Dog2' ;With "CAT" in Dog2, Dog1 is now GREATER THAN (>) Dog2 IF Dog1 < Dog2 print "Would this be printed?" ;above, the print is ignored, since Dog1 is GREATER THAN (>) ;Dog2, not LESS THAN (<) Dog2 EXAMPLE 2 variable number ;define a variable called 'number' printnc "Enter a number from 1 to 10: " gets number 2 ;2 is the max characters to get IF number <= 5 print "The number is less than or equal to 5." IF number > 5 print "The number is greater than 5." IF number = 10 print "The number is 10." IF number > 1 IF number < 10 print "The number is between 1 and 10." ;Example of 'nested' IFs IF number < 5 IF number = 1 print "The number is 1." ELSE printnc "The number is less than five and ... " IF number = 2 print "The number is 2." IF number = 3 print "The number is 3." ELSE print "The number is 4." ENDIF ENDIF EXAMPLE 3 variable attempts ;define variable 'attempts' (set to 0 automatically) variable success ;define variable 'success' "" "" when "Name?" send "John Smith" when "password?" IF attempts <= 3 ;if less than or equal to 3 send "mypassword" inc attempts ;INCrement; attempts = attempts + 1 ELSE Intellicomm v2.01 SCRIPT.DOC 111 stamp "Too many password failures." goto LOGON_ERROR ENDIF when "More?" send "N" waitfor "Main Menu:" 120 LOGON_ERROR assign success 1 ;variable 'success' will be 1 if we found the ; Main Menu: prompt, or will be 0 if we jumped ; to LOGON_ERROR LOGON_ERROR: IF success = 1 ;if variable 'success' is equal to 1 alarm ELSE stamp "Logon unsuccessful." hangup ENDIF return INC______________________________________________________________________ SUMMARY INC vNUM DESCRIPTION Adds 1 to the contents of the variable vNUM (vNUM = vNUM + 1). SEE ALSO ADD, DEC EXAMPLE variable x 10 ;define 'x' and assign 10 to it inc x ;increment the contents of 'x' print x ;prints 11 INITMODEM________________________________________________________________ SUMMARY INITMODEM DESCRIPTION Displays a message to the user, flushes the send/transmit buffers (RXFLUSH, TXFLUSH) sends the main setup "Initialize Modem" string to the modem (*minit variable), then waits for 1.5 seconds for the COM port DCD (carrier detect) signal to return to normal. Some modems fluctuate the Intellicomm v2.01 SCRIPT.DOC 112 COM port online/offline status after an ATZ (reset) command, which is often used in modem init strings... and this can cause Intellicomm to think that a connection was established then lost. Thus, INITMODEM waits for the modem to settle down before returning to Intellicomm. Note that your modem must be in "command state" or it will simply send the Initialize Modem string over the telephone line (to the BBS) if you're already online. You can activate command state on most modems by sending three plus signs and waiting for a second or two. See the example below for more details. ERRORLEVEL SEE ALSO EXAMPLE if $carrier = 0 ;offline? No problem INITMODEM else ;This may or may not work... it depends on the modem. It's ; provided more for demonstration purposes than anything. It ; really shouldn't be necessary to re-initialize the modem while ; online. send "+++~" ;put modem into command state INITMODEM ;send the init string send "ATO" ;return to online state (exit command state) endif INKEY____________________________________________________________________ INKEYT___________________________________________________________________ INKEYW___________________________________________________________________ SUMMARY INKEY vKEYCODE INKEYW vKEYCODE INKEYT vKEYCODE nTIMEOUT DESCRIPTION These commands get a single key stroke from the keyboard and store its code (see Keyboard Codes Appendix) in vKEYCODE. IMPORTANT NOTE: If you plan to use any of the above commands, you must first set $KEY_CHECK to 0 (shut off regular terminal mode key checks), or the script processor will eat most of the keystrokes before INKEY/W/T gets to them. This is more important with INKEY than it is for INKEYW or INKEYT, since INKEY doesn't WAIT for a keypress: it just makes a quick check of the keystroke buffer. Example: variable key assign $KEY_CHECK 0 ;shut off regular keyboard checking Intellicomm v2.01 SCRIPT.DOC 113 while 1 INKEY key ;this now gets EVERY keystroke if key = "^[" break ;[Esc] pressed? endwhile assign $KEY_CHECK 1 ;always turn it back on when you're done Note that the key needn't actually be physically pressed at the time that INKEY is called ... IBM PC's (XT/AT/386/486,etc) buffer keystrokes in internal memory locations called the "keyboard buffer" when the user actually presses a key (where the keycode is saved even after the key is released), and INKEY/INKEYW/INKEYT simply check the keyboard buffer. So you needn't worry about "timing" your use of INKEY/INKEYW/INKEYT with the user's actual key presses. On the other hand, if you don't WANT the buffered keystrokes (there's no way to tell how old they are), call KBFLUSH to flush the keyboard buffer, just after you ask for input: print "Press a key..." KBFLUSH ;ensures no "old" keystrokes take effect INKEYW key INKEY quickly checks the keyboard buffer for any pressed keys. If a new keycode is waiting, its value is stored in vKEYCODE. Otherwise 0 (zero) is stored in vKEYCODE. You'll use this variation when you want to check for keys WHILE doing something else (displaying information on the screen, etc) at the same time, as illustrated just above in the WHILE loop. INKEYW waits for a key press (if no keys are waiting in the keyboard buffer when it's called). Your script does not continue until the user has actually pressed a key, at which point the key pressed will be stored in vKEYCODE, and the script will continue. INKEYT is an INKEYW with a timeout (specified in tenths of a second). It waits for nTIMEOUT tenths of a second for a key press. If a key is pressed (or is waiting in the keyboard buffer when INKEYT is called), it immediately stores the keycode in vKEYCODE and returns. If no key is pressed within nTIMEOUT tenths of a second, INKEYT returns (your script continues execution) and vKEYCODE will be 0 (zero). Please see the KEYBOARD CODES appendix for a list of all keyboard codes. ERRORLEVEL None of these commands set $ERRORLEVEL. You can get all the information you need by checking the vKEYCODE variable you specify. For a list of key codes, see KEYBOARD CODES in the online help and/or SCRIPT.DOC. SEE ALSO BOXGETS, GETS, $KEY_ALTQ, $KEY_CHECK EXAMPLE variable keycode ;always need a variable to store codes in Intellicomm v2.01 SCRIPT.DOC 114 printnc "Press a key, or [Esc] to abort: " INKEYW keycode if keycode = "^[" exit printnc "Press a key: " INKEYT keycode 100 ;ends the pause after 10 seconds if no key pressed ;This bit below updates an on-screen clock where [Alt-Z] for Menu is ; usually displayed on the status line, while also processing user ; keystrokes. variable cur_sec variable last_sec -1 ;first erase "Alt-Z for Menu" on the status line (bottom screen line) scroll 66 $SCRN_HEIGHT 80 $SCRN_HEIGHT 0 $STAT_COLOR while 1 ;endless loop (until BREAK) INKEY keycode ;keep going if nothing there if keycode = "^[" break ;we only want to update the clock once per second, or it will flicker substr cur_sec $TIME 7 1 ;HH:MM:SS .. gets the last 'S' (second) char if cur_sec = last_sec continue assign last_sec cur_sec printraw 69 $SCRN_HEIGHT $STAT_COLOR $TIME endwhile assign $STAT_ON 0 ;re-draw the original status line assign $STAT_ON 1 KBFLUSH__________________________________________________________________ SUMMARY KBFLUSH DESCRIPTION When the user presses keys on the keyboard, the computer stores the key code(s) in the "keyboard buffer". The keys will sit in this buffer until Intellicomm or your script actually gets it/them one by one with INKEY, INKEYW, INKEYT, or a menu function (MENUBAR, MENUBOXH, MENUBOXV), or GETS, BOXGETS (though GETS/BOXGETS automatically call KBFLUSH on entry). If there's a critical error message or the like you must display to the user though, and you want to ensure that some previous keystroke doesn't bypass the message, you can call KBFLUSH to flush any existing keystrokes from the keystroke buffer. Key strokes wait in the keyboard buffer INDEFINITELY, until you call KBFLUSH or one of the INKEY.. / or MENU.. functions. SEE ALSO Intellicomm v2.01 SCRIPT.DOC 115 INKEY, INKEYT, INKEYW EXAMPLE printnc "Are you sure? " menudefine "~Yes" "~No" KBFLUSH menubar LIST_____________________________________________________________________ SUMMARY LIST sFILENAME [nLINENUM] DESCRIPTION Enters Icom's internal File Viewer, or the external viewer defined by the user (main setup/Filenames and Paths screen, main setup variable *flister). sFILENAME is the file to view ([D:][\PATH\]FILENAME[.EXT] a filename with optional drive, path and extension). nLINENUM is only valid when *flister is blank (no external viewer), and it specifies an optional line number to position to after loading sFILENAME. NOTE: If you want to ensure use of Icom's internal File Viewer, simply save the *flister main setup variable, clear it, then call LIST. Example: variable filename $HOME_DIR "SCRTUTOR.DOC" variable oldlister *flister ;save external viewer (if any) assign *flister "" ;clear external viewer LIST filename 100 ;list C:\ICOM\SCR\SCRTUTOR.DOC position to ; line 100 assign *flister oldflister ;restore original external editor This should only be done when you must seek to a specific line number in a file. You should otherwise let the user view files in his preferred external file viewer. SEE ALSO EDIT EXAMPLE variable filename $HOME_DIR "SCRIPT.DOC" pause "Press a key to view SCRIPT.DOC..." LIST filename Intellicomm v2.01 SCRIPT.DOC 116 LOADBIF__________________________________________________________________ SUMMARY LOADBIF sBIFNAME DESCRIPTION Loads the BBS Information File (.BIF) sBIFNAME into memory. Neither the .BIF extension nor the C:\ICOM\BIF directory should be specified: just the BIF filename. BIFs are completely useless on-disk. The only way they can be used is to load them into memory. Icom loads BIFs into memory on its own when dialing, after connecting to a BBS, when importing new files lists, and for various other purposes. You can do the same from your scripts by using LOADBIF and the various BIF Variables outlined in the BIF VARIABLES Appendix of this manual. ERRORLEVEL 0 sBIFNAME is loaded. 1 Unable to load sBIFNAME (file not found). SEE ALSO SAVEBIF EXAMPLE LOADBIF "ICOM" ;load the BIF for the Icom Online Service LOADINI__________________________________________________________________ SUMMARY LOADINI sININAME DESCRIPTION Loads the Main Initialization File (.INI) sININAME into memory. Neither the .INI extension nor the C:\ICOM directory should be specified: just the INI filename. INI files are completely useless on-disk. The only way they can be used is to load them into memory. Icom loads ICOM.INI (the default main setup file) into memory on its own at program startup. You can later load other main setup files from your scripts by using LOADINI and the various Main Setup Variables outlined in the MAIN SETUP VARIABLES Appendix of this manual. ERRORLEVEL 0 sININAME is loaded. Intellicomm v2.01 SCRIPT.DOC 117 1 Unable to load sININAME (file not found normally). SEE ALSO SAVEINI EXAMPLE LOADINI "CUSTOM" ;load the CUSTOM.INI file settings LOCATEFILE_______________________________________________________________ SUMMARY LOCATEFILE vBUFFER sFILESPEC ... DESCRIPTION LOCATEFILE searches for sFILESPEC. If an explicit D:\PATH is specified in sFILESPEC, only the specified directory is searched. If no directory is specified, LOCATEFILE searches all directories on the Upload PATH, the Download Directory, and (if the Main Setup variable *pathsch is non- zero) all directories on the DOS PATH. If the file is found, its full D:\PATH\FILENAME.EXT is stored in variable vBUFFER. sFILESPEC specifies the file to search for. DOS wildcard characters * and ? are accepted, and, as mentioned above, you may specify an optional D:\PATH to search in a specific directory. NOTE: LOCATEFILE does not locate directories or hidden files (it's meant to be used to locate files for uploading, and neither directories nor hidden files can be uploaded). Use FINDFIRST to locate these. ERRORLEVEL 0 sFILESPEC was found and the full D:\PATH\FILENAME.EXT has been stored in vBUFFER. 1 sFILESPEC was not found. Try using DISKFIND if appropriate. SEE ALSO EXIST, FINDFIRST, DISKFIND EXAMPLE variable file LOCATEFILE file "ICOM201A.ZIP" if $errorlevel = 0 upload "Z" file LOG______________________________________________________________________ SUMMARY Intellicomm v2.01 SCRIPT.DOC 118 LOG [sLOGNAME] DESCRIPTION Opens the Usage Log. If sLOGNAME is omitted, the default Usage Log filename (\ICOM\CAP\ICOM.USE, or the filename defined on the main setup Filenames and Paths screen) is assumed. If the drive, path or extension is omitted in sLOGNAME the D:\PATH .EXT of the last Usage Log is assumed. SEE ALSO LOGCLOSE, STAMP EXAMPLE LOG "TEMP" ;open a temporary usage log LOGCLOSE_________________________________________________________________ SUMMARY LOGCLOSE DESCRIPTION Closes the Usage Log. SEE ALSO LOG, STAMP MENUBAR__________________________________________________________________ SUMMARY MENUBAR nX nY [nSTART] DESCRIPTION Activates the last menu defined with MENUDEFINE in 'bar' format, at screen position nX (column, left to right), nY (row, top to bottom). Menu items run horizontally from screen coordinates nX, nY, and no box is displayed around the menu. If help is attached to a given menu item (with MENUHLP), its help text is displayed immediately under the first menu item when it is hilighted (as in the Icom Job Directory, BBS Directory bottom menus). If the optional nSTART parameter is specified, the current menu position (hilight) will be set to menu item # nSTART (1st menu option being item 1, 2nd being item 2, etc) when the menu is first displayed. I.e. this is the 'default' menu option. Intellicomm v2.01 SCRIPT.DOC 119 ERRORLEVEL MENUBAR does not set $ERRORLEVEL. A separate variable called $MENUSELECTION is instead used to hold the last menu selection, undisturbed, from one menu use to the next. After MENUBAR finishes $MENUSELECTION will be set to one of the following values: 0 = [Esc] or right mouse button pressed (nothing selected). 1+ = If $MENUSELECTION is 1 or greater, the user selected the corresponding menu item. If set to 1, the user selected the first menu option. Hidden or disabled menu items (see MENUITEMSTAT) still count as valid menu items. SEE ALSO MENUBOXH, MENUBOXV, MENUDEFINE, MENUHLP, MENUITEMSTAT, $MENUSELECTION EXAMPLE Please see SCRDEMO.SCR, included with Intellicomm, for several working examples of menu usage. MENUBOXH_________________________________________________________________ SUMMARY MENUBOXH [sTITLE] [sHELPLINE] [nSTART] DESCRIPTION A picture is worth a thousand words. MENUBOXH gives you the following (using graphics characters instead of +=), where "Item 1 Item2 Item3 ..." is the last menu defined with the MENUDEFINE command: +=| sTITLE |====================+ | | | sHELPLINE | | | | Item 1 Item 2 Item 3 ... | | | +===============================+ The box is displayed centered on the screen. If the optional nSTART parameter is specified, the current menu position (hilight) will be set to menu item # nSTART (1st menu option being item 1, 2nd being item 2, etc) when the menu is first displayed. I.e. nSTART is the 'default' menu option offered to the user. If sTITLE or sHELPLINE is longer than the combined length of the menu items, the box will be adjusted accordingly. If sHELPLINE is not specified the menu appears as follows: +=| sTITLE |====================+ | | | Item 1 Item 2 Item 3 ... | | | Intellicomm v2.01SCRIPT.DOC 120 +===============================+ You can also display sHELPLINE and the menu items all on the same line by using a TAB character as the first character in the sHELPLINE text. Example (^I is a TAB): MENUDEFINE "~Yes" "~No" MENUBOXH "Title" "^IContinue?" This would give you the following: +=| Title |============+ | | | Continue? Yes No | | | +======================+ It is UP TO YOU to ensure that the menu can be displayed properly. If you define too many menu items to fit on the screen, or your help line/title is too long, the menu will be a mess. ERRORLEVEL MENUBOXH does not set $ERRORLEVEL. A separate variable called $MENUSELECTION is instead used to hold the last menu selection, undisturbed, from one menu use to the next. After MENUBOXH finishes $MENUSELECTION will be set to one of the following values: 0 [Esc] or right mouse button pressed (nothing selected). 1+ If $MENUSELECTION is 1 or greater, the user selected the corresponding menu item. If set to 1, the user selected the first menu option, if 2 the second option was selected and so forth. Hidden or disabled menu items (see MENUITEMSTAT) still count as valid menu items. SEE ALSO MENUBAR, MENUBOXV, MENUDEFINE, MENUHLP, MENUITEMSTAT, $MENUSELECTION EXAMPLE Please see SCRDEMO.SCR, included with Intellicomm, for several working examples of menu usage. MENUBOXV_________________________________________________________________ SUMMARY MENUBOXV [sTITLE] [sHELPLINE] [nSTART] DESCRIPTION Displays the last menu defined with MENUDEFINE in 'vertical box' menu format, as follows: Intellicomm v2.01SCRIPT.DOC 121 +=| sTITLE |==+ | | | sHELPLINE | | | | Item 1 | | Item 2 | | Item 3 | +=============+ The box size is adjusted to fit the longest item, whether sTITLE, sHELPLINE, or one of the menu items is the longest. The nSTART parameter is the optional menu item to hilight at menu startup (1 = hilight menu item 1, 2 = hilight menu item 2, etc). If sHELPLINE is omitted, the menu is displayed as follows: +=| sTITLE |==+ | | | Item 1 | | Item 2 | | Item 3 | +=============+ When you plan to use MENUBOXV, you can also use menu "lines" in the menus you define. Example: MENUDEFINE "Item ~1" "Item ~2" "-" "Item ~3" "Item ~4" MENUBOXV " The commands above would produce the following menu: +=| Title |=+ | | | Item 1 | | Item 2 | |-----------| | Item 3 | | Item 4 | +===========+ ERRORLEVEL MENUBOXV does not set $ERRORLEVEL. A separate variable called $MENUSELECTION is instead used to hold the last menu selection, undisturbed, from one menu use to the next. After MENUBOXV finishes $MENUSELECTION will be set to one of the following values: 0 = [Esc] or right mouse button pressed (nothing selected). 1+ = If $MENUSELECTION is 1 or greater, the user selected the corresponding menu item. If set to 1, the user selected the first menu option. Hidden or disabled menu items (see MENUITEMSTAT) still count as valid menu items. Menu lines do not count as menu items. SEE ALSO Intellicomm v2.01 SCRIPT.DOC 122 MENUBAR, MENUBOXH, MENUDEFINE, MENUHLP, MENUITEMSTAT, $MENUSELECTION EXAMPLE Please see SCRDEMO.SCR, included with Intellicomm, for several working examples of menu usage. MENUDEFINE_______________________________________________________________ SUMMARY MENUDEFINE ITEM1 ITEM2 [ITEM3] ... DESCRIPTION Defines a list of two or more menu options for use with MENUBAR, MENUBOXH (horizontal menu options in a box) and MENUBOXV (vertical menu options in a box). ITEM1 is the first menu option, ITEM2 is the second menu option, [ITEM3] ... is the third and following menu option(s) (the square brackets denote an optional item and should not be used). A tilde (~) may (and should) be used within each ITEMx parameter to define the position of the item 'hotkey' (e.g. "~Yes" "~No"). The letter following the tilde will be displayed in 'bold' text, and can be used to select the menu option, once the menu is displayed, without moving the hilight bar. Use of the tilde is optional, and if you omit a tilde the item will not have a hotkey. If you're not careful, you can also inadvertantly assign the same hotkey to two different menu options. If this happens, when the user presses the hotkey, the FIRST item that uses that hotkey will be selected. When using the MENUBOXH command (menu items are stacked on top of one another in a box) you can also use a single hypen as a menu option ("-") to specify a box divider line as you see on many of Icom's vertical box menus (e.g. MENUDEFINE "Item ~1" "-" "Item ~2"). NOTE: No limits are enforced as to the number of options you can define with MENUDEFINE, but the screen size (and the type of menu you choose to use) may cause your menu to malfunction if you get out of hand with MENUDEFINE and define too many options. Experience (trial and error) is the only reliable way to find the limits. If you specify EGA/VGA extended line video modes (42/50 lines) in the Icom main setup, you can fit more menu options in a MENUBOXH (horizontal box) than you could on a 25-line display. Be sure to take this into account if you plan to distribute your scripts to others who may not have an EGA/VGA display. It's best to test your menus in 25-line video mode before distribution. SEE ALSO MENUBAR, MENUBOXH, MENUBOXV, MENUHLP, MENUITEMSTAT, $MENUSELECTION EXAMPLE MENUDEFINE "~Sure, no problem" "~No Thanks" Intellicomm v2.01 SCRIPT.DOC 123 if $DL_PROTOCOL = "Z" goto start ;if the D/L protocol is Zmodem boxmenuh "Wrong Protocol!" "Okay to use Zmodem?" if $ERRORLEVEL <> 1 goto done ;the user didn't select "Sure" assign $DL_PROTOCOL "Z" ;change the D/L protocol to Zmodem start: ;main body of script here done: return ;exit the script or subroutine MENUHLP__________________________________________________________________ SUMMARY MENUHLP nMENUITEM nHELPTEXT DESCRIPTION Attaches the text nHELPTEXT to menu item number nMENUITEM. A menu must be defined with MENUDEFINE before using MENUHLP. On bar menus (MENUBAR, MENUBOXH) the nHELPTEXT is displayed under the bar menu as each item is hilighted, similar to Intellicomm's Job Directory bottom bar menu. On vertical menus (MENUBOXV) nHELPTEXT is displayed on the bottom screen line as each item is hilighted, as demonstrated in the SCRDEMO.SCR main menu. ERRORLEVEL None. If nMENUITEM is invalid the script aborts and the error is pointed out to you. SEE ALSO MENUDEFINE, MENUITEMSTAT EXAMPLE menudefine "Item ~1" "Item ~2" "Item ~3" MENUHLP 1 "Item 1 description" MENUHLP 2 "Item 2 description" MENUHLP 3 "Item 3 description" menubar MENUITEMSTAT_____________________________________________________________ SUMMARY MENUITEMSTAT nMENUITEM nSTATUS DESCRIPTION Sets or clears the disabled and/or hidden status of menu item nMENUITEM. Intellicomm v2.01 SCRIPT.DOC 124 MENUDEFINE must be used before MENUITEMSTAT. Values for nSTATUS: 0 Clear hidden/disabled status of nMENUITEM 1 Disable nMENUITEM 2 Hide nMENUITEM ERRORLEVEL None. If nMENUITEM is invalid the script aborts and the error is pointed out to you. SEE ALSO MENUDEFINE, MENUHLP EXAMPLE menudefine "Item ~1" "~Unhide Item 3" "Item ~3" MENUITEMSTAT 3 2 ;Hide item 3 again: menubar if $menuselection = 2 ;'Unhide Item 3' selected? MENUITEMSTAT 3 0 ;Unhide item 3 goto again ; and redisplay the menu endif MKDIR____________________________________________________________________ SUMMARY MKDIR sPATH DESCRIPTION Creates the directory(s) specified by sPATH (same as MKDIR from DOS). You can make multiple directories with a single call to MKDIR. For example, if the directory \TEST doesn't exist, the following will make both \TEST and \TEST\TEST1 directories: MKDIR "\TEST\TEST1" ERRORLEVEL 0 sPATH was created. 1 sPATH couldn't be created (invalid drive or path, or root directory full). 4 Permission denied (directory already exists). 5 Miscellaneous errors. The directory wasn't created. SEE ALSO Intellicomm v2.01 SCRIPT.DOC 125 RMDIR EXAMPLE MKDIR "$TEMP$" ;create a temporary directory in the current directory MSGOPEN__________________________________________________________________ SUMMARY MSGOPEN sMESSAGE ... DESCRIPTION Displays sMESSAGE in a centered message box. Call MSGCLOSE to remove the message box. SEE ALSO MSGCLOSE, MSGWIND EXAMPLE variable k MSGOPEN "Please press a key..." inkeyw k msgclose MSGCLOSE_________________________________________________________________ SUMMARY MSGCLOSE DESCRIPTION Closes a message window opened with MSGOPEN (restores the previous screen contents). SEE ALSO MSGOPEN, MSGWIND EXAMPLE variable k msgopen "Searching for SCRTUTOR.DOC..." diskfind "SCRTUTOR.DOC" MSGCLOSE MSGWIND__________________________________________________________________ SUMMARY Intellicomm v2.01 SCRIPT.DOC 126 MSGWIND sMESSAGE ... DESCRIPTION Displays sMESSAGE in a centered box on screen, pauses for *sdelay TENTHS of a second, then closes the message box. Use MSGWIND for status messages such as "Finished!", where it isn't imperative that the user see the message. SEE ALSO MSGOPEN, MSGCLOSE EXAMPLE MSGWIND "It is now: " $TIME ;display the current time MUL______________________________________________________________________ SUMMARY MUL vPRODUCT nMULTIPLICAND nMULTIPLIER DESCRIPTION Multiplies nMULTIPLICAND by nMULTIPLIER and stores the result in vPRODUCT. As with any multiplication, the order of the multiplicand and multiplier is irrelevant: 7 x 4 = 28, as 4 x 7 = 28. SEE ALSO ADD, DIV, SUB EXAMPLE variable result MUL result 10 5 ;stores 10 x 5 (50) in variable 'result' print result NEWAREA__________________________________________________________________ SUMMARY NEWAREA sAREA DESCRIPTION NEWAREA is a powerful command that can literally save you hours of script writing. It uses the currently loaded BIF data to reliably access the BBS 'Main Menu', 'Message Menu', 'Bank Menu', or 'File Menu' to/from any other menu. I.e. if you're in the File Menu and want to get to the Bank Menu, you needn't worry about how to exit the file menu nor how to access the Bank Menu, nor worry about which BBS prompts to handle for either task. Icom uses the BIF information to handle the whole shot Intellicomm v2.01 SCRIPT.DOC 127 with a single call to NEWAREA. You can also change BBS message/file areas with NEWAREA, again without worrying about how to go about it. Icom uses the BIF data to make the change, and handles all the BBS prompts on the way. It also makes use of Icom's error-handling routines (timeouts/BIF General menu exits, and it will re-try up to three times total if the initial area change fails). NEWAREA determines a change area request according to the sAREA parameter. If sAREA is 'L', 'M', 'F', or 'B' enclosed in square brackets NEWAREA accesses the following BBS menu: [L] The Logon Menu (the Main Menu A, Main Menu B prompts defined on BIF Logon screen). [M] The 'Message Menu' defined on the BIF Message screen. To access this menu, the BIF 'Access Msg. Menu' command will be sent, to leave it (if NEWAREA is at the Message Menu and you perform for example a NEWAREA [B]) the 'Leave Msg Menu' command is used. NOTE: You needn't check the BIF to see whether an 'Access Msg. Menu' command is defined: if nothing is defined, Message functions can be carried out from the BBS [L]ogon (Main) Menu, and that is the menu NEWAREA will change to, if necessary. [F] The 'File Menu' defined on the BIF Message screen. To access this menu, the BIF 'Access File Menu' command will be sent, to leave it (if NEWAREA is at the File Menu and you perform for example a NEWAREA [B]) the 'Leave File Menu' command is used. [B] The 'Bank Menu' defined on the BIF Message screen. To access this menu, the BIF 'Access Bank Menu' command will be sent, to leave it (if NEWAREA is at the Bank Menu and you perform for example a NEWAREA [M]) the 'Leave Bank Menu' command is used. If you specify anything OTHER than a single letter enclosed in square brackets, NEWAREA assumes a message/file area change and will issue the "Area Change" command defined on the BIF File screen. NEWAREA keeps track of the current area and will not send redundant commands to access a menu/file area if you're already there. Thus you can place calls to NEWAREA virtually anywhere in your script, just to make sure you're where you want to be. If you're already there, NEWAREA sends no commands. If you're at a different location, NEWAREA makes the change. Of course this logic relies on the fact that you haven't changed areas behind NEWAREA's back. If you use NEWAREA, you should use *only* NEWAREA to change BBS areas. If you use SEND "OPEN QMAIL4" to access the Qmail door (Message Menu) or SEND "J 2"' to [J]oin a new conference, NEWAREA won't know about it and may fail the next time you call it. If you run your script from an automated job, and if Icom was at a main menu when your script was started, NEWAREA will already know which area of the BBS it's at (Icom keeps track of the current BBS area during automated jobs). If you run your Script from the Script Manager or from the DOS command line, NEWAREA will first send the BIF General Menu Exit command (a couple of Ctrl-K's and ENTER normally) to locate its position on the BBS before attempting to change areas. Intellicomm v2.01 SCRIPT.DOC 128 NOTE: In order to perform BBS area changes, Intellicomm uses the WHEN slots which scripts use to track BBS prompts. Since the script WHEN data and Intellicomm's own tracking routines use same memory space, any previously defined WHEN data is lost. All WHENs are cleared when NEWAREA finishes. I.e. do NOT use the NEWAREA command during a WHEN/WAITFOR, unless you use a GOTO to jump to the NEWAREA command, and then use another GOTO to get back above the WHENs to re-define them when NEWAREA finishes: redefine_whens: WHEN "prompt1" send "response 1" WHEN "prompt2" goto change_areas WAITFOR "prompt3" 120 return change_areas: NEWAREA "[M]" ;change to the message menu... WHENs are lost goto redefine_whens ;get back up to re-define the WHEN/WAITFOR Further, if you're experienced with WHEN and know that it needn't actually be called immediately prior to a WAITFOR (i.e. you can execute the WHENs anywhere... Icom stores the data in memory and makes use if it the next time it runs into a WAITFOR), you'll have to take this into consideration if you use the NEWAREA command. This will NOT work: WHEN "prompt 1" send "response 1" WHEN "prompt 2" send "response 2" ;later in the script you usually 'can' call WAITFOR and the WHENs ; would still be stored in memory. But... if you use NEWAREA: NEWAREA "[L]" ;Access the [L]ogon Menu (BBS Main menu) ;the WHENs defined above are now gone send "some command" WAITFOR "some menu" 120 ;simply waits... no WHENs are active ERRORLEVEL 0 Area change successful. 1 Area change unsuccessful (3 attempts failed, the connection was lost, etc). 2 No BIF loaded. You must call your script from an automated job (in which case the proper BIF data will already be loaded) or must use the LOADBIF or DIAL command to load a BIF into memory. SEE ALSO $BBS_AREA EXAMPLE NEWAREA "2" ;Access conference 2; Sends J 2 Q on PCBoard systems Intellicomm v2.01 SCRIPT.DOC 129 if $ERRORLEVEL <> 0 return NEWAREA [M] ;Access the Message Menu if $ERRORLEVEL <> 0 return NOTEXIST_________________________________________________________________ SUMMARY NOTEXIST sFILESPEC cCOMMAND DESCRIPTION If sFILESPEC does NOT exist, cCOMMAND is executed. If sFILESPEC does exist, cCOMMAND is skipped. sFILESPEC is a file specification (wildcards * and ? are accepted) including an optional drive and path (D:\PATH\*.BAT for example). If you omit the drive (D:) the current drive ($CURDRIVE) is assumed. If both the drive and path are omitted, the current path is assumed ($CURDIR). ERRORLEVEL No errorlevel is necessary. Use cCOMMAND. SEE ALSO DISKFIND, EXIST, FINDFIRST, FINDNEXT EXAMPLE variable filename $HOME_DIR "POSTDOWN.BAT" exist filename edit filename ;edit POSTDOWN.BAT if it exists OFFLINE__________________________________________________________________ SUMMARY OFFLINE cCOMMAND DESCRIPTION If the modem is offline (not connected) cCOMMAND is executed. If the modem is online (connected) cCOMMAND is skipped. SEE ALSO ONLINE, $CARRIER EXAMPLE OFFLINE exit ;exit the script if modem is not online Intellicomm v2.01 SCRIPT.DOC 130 ONLINE___________________________________________________________________ SUMMARY ONLINE cCOMMAND DESCRIPTION If the modem is online (connected) cCOMMAND is executed. If the modem is offline (not connected) cCOMMAND is skipped. SEE ALSO ONLINE, $CARRIER EXAMPLE ONLINE exit ;exit the script if modem is online OR_______________________________________________________________________ SUMMARY OR vRESULT nNUM nBITMASK DESCRIPTION Performs a bitwise OR on nNUM using nBITMASK, and stores the result in vRESULT. Unless you're a programmer, you probably will never find a use for OR. SEE ALSO AND, SHL, SHR, XOR EXAMPLE variable someflag 0 OR someflag someflag 1 ;set bit 1 in variable 'someflag' PAUSE____________________________________________________________________ SUMMARY PAUSE [MESSAGE] ... DESCRIPTION PAUSE displays an optional message to the user (if specified), then pauses script execution until the user presses a key. If MESSAGE is specified it is printed at the current cursor position ($SCRN_X, $SCRN_Y) in the current screen color ($SCRN_COLOR). The cursor (if on) will be displayed immediately following the message until the user presses a key. Once a key is pressed, and if a MESSAGE was displayed, Intellicomm v2.01 SCRIPT.DOC 131 PAUSE prints "^M^J" (Carriage Return/Line Feed) to the screen to advance the cursor to the next screen line (terminating the line that MESSAGE was on). And the script continues executing at the next script line (if any). Please also see the notes in the PRINT summary below. SEE ALSO BOXGETS, GETS, INKEY, INKEYW, INKEYT, PRINT, PRINTNC, PRINTRAW, WINDOW, WNDOPEN EXAMPLE PAUSE "Press a key to continue: " PRINT____________________________________________________________________ SUMMARY PRINT DATA ... DESCRIPTION Displays DATA (either a number, string, or variable) on the screen in the current $SCRN_COLOR, at the current cursor position ($SCRN_X, $SCRN_Y) and follows it with a Carriage Return/Line Feed to terminate the line. If DATA is too long to be displayed in the current WINDOW, it is either wrapped to the next screen line, or truncated (cut) at the current $WND_RIGHT position, depending on the setting of $SCRN_WRAP (0 = truncate, 1 = wrap). NOTE 1: If the capture file is currently open (see CAPTURE), data you display with PAUSE, PRINT, and PRINTNC is also written to the capture file. To display data on the screen without capturing it, either turn capture off temporarily (CAPPUSH, then CAPCLOSE or CAPPAUSE, then CAPPOP to restore) or use the PRINTRAW command. NOTE 2: There are several characters you cannot print to the screen with the PRINT command. PAUSE, PRINT, and PRINTNC perform special functions on certain control characters, if present in the data being printed. The table below lists all these characters: the ASCII code (number) is first, the characters used to signify the control character in a string comes second (PRINT "^M" prints CR), the control character name (ESC, CR, etc.) is third, and a description of the Function it performs if printed with PAUSE, PRINT, or PRINTNC is fourth: Num Char Name Function ------------------------------------------------------------------------ - 2 ^B STX Toggles 'bold' text on/off. PRINT always starts printing text in the color that $SCRN_COLOR is set to. If ^B is encountered, $SCRN_COLOR is temporarily set to $BOLD_COLOR. When another ^B is encountered (or if the end of the PRINT string is reached) the previous screen Intellicomm v2.01 SCRIPT.DOC 132 color is reset. Example: PRINT "Normal ^BBold^B Normal" The word "Bold" above would be printed in $BOLD_COLOR due to the ^B's surrounding it. The rest of the string would be printed in $SCRN_COLOR. 5 ^E ENQ Sends the ENQuiry response to the BBS (if any; defined on the main setup "Terminal" screen). You'll never want to do this... it's just mentioned because that's what'll happen if you try to print this character. PRINT sends characters through the terminal display, and the terminal display responds to ^E ENQuiry, if found. 7 ^G BEL Same as using BEEP. If you have something important to PRINT to the user, you can beep to wake him/her up. Example: PRINT "^GHey, wake up!" Note that if $SOUND is equal to 0 (zero), ^G characters make no sound, whether used in PAUSE, PRINT, or PRINTNC, or received from the COM port. 9 ^I HT Horizontal Tab moves to the next tab column. Tab columns exist every five characters from the left of the current WINDOW ($WND_LEFT). You can line up columns of data (a filename, date, size, etc) on these tab columns, by using tabs (^I) in your PAUSE, PRINT, PRINTNC statements. 10 ^J LF Line Feed moves the cursor down one row (top to bottom), keeping it in the same screen column (left to right). If the cursor is at the bottom of the current WINDOW when ^J is printed, the contents of the window scrolls up one line. Use both ^M^J (CR/LF) if you want to move the cursor to the beginning of the new line. Note that PRINT and PAUSE (after the key is pressed) both automatically add ^M^J to the end of the data they print. PRINTNC does not. 12 ^L FF Form Feed is the same as CLS (clear current WINDOW, move cursor to position 1,1). 13 ^M CR Carriage Return moves the cursor to screen column 1 (leftmost column, according to the current WINDOW, if any) maintaining the current screen row. Follow ^M with ^J (Line Feed) to move to the next line. 24 ^X CAN CANcel is the beginning of the Zmodem auto-download sequence. If *zauto (Zmodem auto-downloads on/off, main setup variable) is non-zero, ^X will be "eaten" by PAUSE, PRINT, and PRINTNC. If *zauto is set to zero, ^X is printed to the screen. 27 ^[ ESC Signifies the beginning of an ANSI escape code. This character (and perhaps one or more characters following it, depending upon what follows) is never displayed by PAUSE, PRINT or PRINTNC. To print any of the above characters to the screen directly, instead of having the terminal act upon the character, use the PRINTRAW command which writes directly to the screen without going through the terminal display routines. SEE ALSO Intellicomm v2.01 SCRIPT.DOC 133 PAUSE, PRINTNC, PRINTRAW, WINDOW, WNDOPEN EXAMPLE variable myvariable assign myvariable "some information" PRINT "Here is " myvariable " to read." ;Displays "Here is some information to read." (without the quotes). PRINTNC__________________________________________________________________ SUMMARY PRINTNC [sDATA] ... DESCRIPTION Performs the same function as PRINT (see above), but PRINTNC does not add a Carriage Return/Line feed after sDATA. I.e. you can use several PRINTNC commands to print data on the same screen line (though you can also accomplish that by specifying multiple parameters after a PRINT statement). Please read the PRINT summary above for special considerations. SEE ALSO PAUSE, PRINT, PRINTRAW, WINDOW, WNDOPEN EXAMPLE variable keypressed ;This performs basically the same function as PAUSE, but you can ; check the key to see what the user pressed (you might want to cancel ; something if ^[ (ESC) is pressed) PRINTNC "Please press a key: " inkeyw keypressed PRINT ;prints only ^M^J (CR/LF) to terminate the PRINTNC line above. PRINTRAW_________________________________________________________________ SUMMARY PRINTRAW nX nY nCOLOR DATA ... DESCRIPTION Displays DATA (one or more constant strings/numbers or variables) on the video display at screen row nX, column nY (1 1 being the top left screen corner), in color nCOLOR. See COLOR CODES in the online help, or in the Appendix of this manual for information on creating your own colors. Intellicomm v2.01 SCRIPT.DOC 134 Usually you'll use one of the Icom system colors ($SCRN_COLOR, $BOLD_COLOR, etc) as the nCOLOR parameter. Note that PRINTRAW does not observe the current screen WINDOW nor does it move the screen cursor. This allows you to print data on the status line (if it's on ... see $STAT_ON), or outside the current WINDOW, to print data in a window border opened with WNDOPEN for example. Further, you can display any ASCII character with PRINTRAW. Several control characters perform functions when printed with PAUSE, PRINT or PRINTNC, while PRINTRAW displays all characters in their "raw" format (hence the name of the command). PRINTRAW is also faster than PRINT/PRINTNC, since it needn't observe the current WINDOW, nor perform translations of control characters. SEE ALSO BOX, PRINT, PRINTNC, SCROLL EXAMPLE ;Open a window, top corner 1,5, bottom corner 80,20 wndopen "Sample Window" 1 5 80 20 print "This goes inside the window, and you can't get outside with" print "either PAUSE, PRINT or PRINTNC." PRINTRAW 63 5 $BORDER_COLOR " In the Border! " ;Displays " In the Border! " (no quotes) at positon 63,5. Line 5 is the ; top screen border position, and position 63 prints it on the right ; corner. You always have to work out your screen coordinates with ; PRINTRAW. It's more work than using PRINT, but you can do more with ; it. PORT_____________________________________________________________________ SUMMARY PORT nCOMPORT DESCRIPTION Closes the current COM port (any characters received at that port after it's closed will be lost) and opens a new COM port number nCOMPORT. nCOMPORT must be a number from 1 through 8 (for COM1 to COM8). If you use anything above COM4, the proper port address(es) and IRQ information must first be set up on the Icom main setup "Comm Port Setup" screen. By default, all ports above COM4 point to (open) COM1. If a 16550 UART is installed, PORT also enables the 16550 FIFO buffer (if the *16550fl main setup variable is non-zero), and sets its receive and transmit triggers to *16550rx, *16550tx. If you don't understand this, it's not important (though the online help topic "Optimizing Intellicomm v2.01 SCRIPT.DOC 135 Intellicomm" will explain it, if you're interested). If you do understand it, you'll see that you can use the PORT command to change the 16550 receive/transmit triggers from a script, if necessary. ERRORLEVEL 0 Port successfully opened. 1 No memory for transmit/receive buffers, or unable to initialize the port itself. There's not much to a COM port... you have your base address in the computer's memory and the IRQ line the port uses to send an interrupt to the processor. Both items are dictated by the COM port hardware itself (i.e. see the documentation for your multi I/O card, or your modem docs if an internal modem). Both the base port address and IRQ line can be configured, for any port from 1-8, on the main setup "Comm Port Settings" screen ... so if a port can't be opened (assuming you don't see an "Insufficient memory" message on the screen, which you will if there is no memory for the buffers) you should be able to fix the problem in the main setup. 2 Invalid port specified. You didn't follow the PORT command with a number from 1 through 8. EXAMPLE PORT 4 ;Open COM4 send "This goes out COM4 now." REDIAL___________________________________________________________________ SUMMARY REDIAL DESCRIPTION REDIAL will only be needed when you tag and dial multiple BIFs with the DIAL command. Once DIAL connects to a BBS, it untags that BIF. REDIAL can then be used to dial the remaining tagged BIFs (until it sets $ERRORLEVEL to non-zero, in which case nothing was left to dial). NOTE: Using the DIAL or REDIAL command causes any previously defined WHEN commands (for tracking BBS prompts) to be lost. The dialer uses WHEN itself to track the modem response codes, and when it exits all WHENs are cleared. ERRORLEVEL 0 You are now connected to the BBS/BIF specified in the $BIF_NAME System Variable, and that BIF has been untagged. 1 Nothing left to dial, or user aborted. SEE ALSO DIAL Intellicomm v2.01 SCRIPT.DOC 136 EXAMPLE ;REDIAL is an advanced command, and here follows an advanced example. ; Using the framework below, you could perform a fair equivalent to ; an Icom internal job dialing/logon session. If you're faint of heart, ; or new to Icom scripts, skip this example. dial "!" 0 ;Tag/Dial all BBS's with ! in the BIF description while $errorlevel = 0 ;false if not connected ;Perform the auto-logon using the BIF information. This can log on ; anywhere... as long as the BIF [L]ogon section is set up. when ;clear previous WHENs when *[L]namp sendbif "L" "namc" ;BIF variables, name prompt and command when *[L]pasp sendbif "L" "pasc" ;Password prompt/response when *[L]lanp sendbif "L" "lanc" ;Language prompt/response when *[L]ecnp sendbif "L" "ecnc" ;Confirm prompt/response when *[L]grap sendbif "L" "grac" ;Graphics when *[L]scap sendbif "L" "scac" ;Scan messages when *[L]paup sendbif "L" "pauc" ;Pause when *[L]morp sendbif "L" "morc" ;More when *[E]exac sendbif "E" "exap" ;External Extra A when *[E]exbc sendbif "E" "exbp" ; B when *[E]excc sendbif "E" "excp" ; C when *[E]exdc sendbif "E" "exdp" ; D waitfor *[L]mnap 120 ;wait 2 minutes max. for BBS main menu if $errorlevel = 0 ;WAITFOR worked; we're at the BBS main menu switch $BIF_NAME ; but which BBS did we connect to? case "SOMEBIF1" gosub SomeBIF1_Job endcase case "SOMEBIF2" gosub SomeBIF2_Job endcase ;etc., for all the BIF descriptions you placed ! in endswitch send *[L]lofc ;send the logoff command waitfor *[L]lofp 5 ;wait 5 seconds for the Logged Off prompt else ;WAITFOR timed out print "^M^J^GUnable to logon ... hanging up." endif hangup ;make sure we're disconnected before trying to dial again REDIAL ;Here we are at REDIAL, finally. $ERRORLEVEL will be checked ; at the top of the loop, and we'll exit the loop if no more ; BIFs are tagged (or the user aborts dialing). endwhile return ;All BIFs are finished Intellicomm v2.01 SCRIPT.DOC 137 SomeBIF1_Job: ;carry out a mail run or the like return SomeBIF2_Job: ;whatever needs doing on BBS #2 return RELOADSCRIPT_____________________________________________________________ SUMMARY RELOADSCRIPT DESCRIPTION Reloads the currently executing script from disk, and begins executing it at the beginning again. This command will mainly be of use to script writers who distribute scripts to the general public. It can be used to reload/restart a script after the user has defined some initial setup information. EXAMPLE This example below is similar to what the POSTFILE.SCR does before it has been configured properly. It causes a script to pause and "Edit"/reload itself, until the user sets the script up and removes the setup routine. ;--- ;Attention User: Once you plug the proper information into the variables ; below, please remove these comments right down to the RELOADSCRIPT ; command. print $SCRIPT_NAME " has not been configured yet!" pause "Press a key to Edit..." edit $FULL_SCRIPT_NAME RELOADSCRIPT variable someinfo "Default" ;your main setup variables (what the user sets up) go here... ;the main body of your script goes here... return RENAME___________________________________________________________________ SUMMARY RENAME sSOURCENAME sTARGETNAME DESCRIPTION Intellicomm v2.01 SCRIPT.DOC 138 Renames or moves a file. Wildcards (* and ?) are not permitted. sSOURCENAME may contain a drive and path. If the drive is omitted, the current drive is assumed. If the path is omitted, the current directory is assumed. If sTARGETNAME contains a filename (but no D:\PATH), the file sSOURCENAME is renamed to sTARGENAME. If sTARGETNAME contains only a path (D:\PATH or \PATH, etc) sSOURCENAME is MOVED to the directory specified by sTARGETNAME. ERRORLEVEL 0 sSOURCENAME successfully renamed/moved. 1 Unable to move/rename sSOURCENAME (sTARGETNAME is invalid). 2 sSOURCENAME not found. EXAMPLE variable fname $HOME_DIR "EXCLUDE.KWD" ;Exclude Files keyword list RENAME fname "EXCLUDE.TMP" importnew assign fname $HOME_DIR "EXCLUDE.TMP" RENAME fname "EXCLUDE.KWD" RENUMBER_________________________________________________________________ SUMMARY RENUMBER sFILENAME nNUMTOTAL DESCRIPTION Renumbers the file sFILENAME to a maximum number of backup files specified by nNUMTOTAL. RENUMBER renames files very quickly, placing numbers in either file filename or extension (and backup files) of sFILENAME. Icom uses RENUMBER to rename the ICOM.CAP (capture) file just prior to dialing. sFILENAME can (and should) specify the full D:\PATH\FILENAME.EXT of the mail file you want to renumber. Wildcards (* and ?) are not permitted. If you specify wildcards in sFILENAME you may get a mess. nNUMTOTAL specifies the total number of backups of sFILENAME to keep on disk. ERRORLEVEL 0 RENUMBER successful. 1 sFILENAME not found. EXAMPLE Intellicomm v2.01 SCRIPT.DOC 139 ;Renumber the capture files... cappush capclose renumber $CAP_NAME *capnum cappop RETURN___________________________________________________________________ SUMMARY RETURN [nERRORCODE] DESCRIPTION RETURN pulls double-duty and serves two purposes in the script language. When Icom encounters a RETURN it first checks to see whether you previously executed a GOSUB (Goto Subroutine) command, and if so it simply returns to the line following the GOSUB. However, if RETURN is found and no GOSUB has been executed, Icom ends the current script at that point (RETURNs to the calling script, or back to the automated job, or Script Manager, or wherever the script was called from). The optional nERRORCODE is only checked in the latter case, when RETURN is used to exit a script. Further, nERRORCODE is only of use when your script is called during an automated job, via a job Custom Command or BIF command. In most cases, no nERRORCODE number will be specified at all, and you'll simply use RETURN alone. There are a number of factors that determine what Icom does when a RETURN is found, and what it does if you specify an 'errorcode'. All the details are given in SCRTUTOR.DOC in the section "WHAT HAPPENS WHEN A SCRIPT ENDS?". SEE ALSO GOSUB, SYSTEM EXAMPLE offline goto done ;if not online, goto done ... ;main body of script here done: return ;exit the script RMDIR____________________________________________________________________ SUMMARY RMDIR sDIRECTORY ... DESCRIPTION Removes the directory sDIRECTORY. The directory must be empty (including sub-subdirectories) for RMDIR to succeed. Note that the ... above doesn't mean that you can specify multiple Intellicomm v2.01 SCRIPT.DOC 140 directories to remove. Like all script parameters, ... simply signifies that you can build the last parameter (sDIRECTORY is the last parameter in this case) like this: RMDIR "C:" somevariable anothervariable ... etc. All parameters specified are joined together to make a single parameter. ERRORLEVEL 0 sDIRECTORY was removed. 1 sDIRECTORY couldn't be removed (invalid drive or path). 4 Permission denied (directory not empty). 5 Miscellaneous errors. The directory wasn't removed. SEE ALSO MKDIR EXAMPLE variable tmpdir "\$TEMP$.$$$" mkdir tmpdir ;make a temporary directory off the root directory ... ;do your stuff in the temp directory delete tmpdir "\*.*" ;kill any files you created/copied, etc ; (expands to \$TEMP$.$$$\*.*) RMDIR tmpdir RXFLUSH__________________________________________________________________ SUMMARY RXFLUSH DESCRIPTION 'Flushes' or clears the Receive Buffer (a holding area for characters received from the COM port, that have not been displayed to the screen yet). Use to get rid of line noise, logoff bulletins, etc. SEE ALSO TXFLUSH SAVEBIF__________________________________________________________________ SUMMARY SAVEBIF [sBIF_NAME] DESCRIPTION This advanced script command saves the currently loaded BIF information Intellicomm v2.01 SCRIPT.DOC 141 to disk. If sBIF_NAME is omitted, $BIF_NAME (the current BIF filename) is assumed. Only a filename (JOESBBS, SOMEBIF, etc) is required if sBIF_NAME is specified. You may specify a D:\PATH and extension if necessary (i.e. if you used FINDFIRST/FINDNEXT to locate various BIF filenames) but SAVEBIF always always saves in $BIF_DIR (ASSIGN $BIF_DIR another value to save to another directory) using the extension .BIF. NOTE 1: Don't use SAVEBIF unless you fully understand the LOADBIF command and BIF Variables. SAVEBIF is meant to be used after you modify one or more BIF Variables, and you wish to save the modified information to disk. NOTE 2: If sBIF_NAME is specified and a BIF already exists using the same filename, the existing .BIF will be overwritten. You can use the EXIST or FINDFIRST command to see if a given BIFID already exists: variable bifname "SOME_ID" variable temp assign temp $BIF_DIR bifname notexist temp SAVEBIF bifname ERRORLEVEL 0 SAVEBIF successful. 1 SAVEBIF unsuccessful (disk write error, invalid sBIF_NAME, disk full). SEE ALSO LOADBIF EXAMPLE ;Could be used to automatically change the Logon Name (or anything ; else) in all BIFs. variable bifname $BIF_DIR "*.BIF" variable v findfirst bifname bifname ;store the first BIF in 'bifname' while $errorlevel = 0 substr v *[L]desc 0 1 ;get the 1st character of the BBS/Host Name if v <> "[" ;don't mess with BIF templates... loadbif bifname assign *[L]namc "Joe Smith" SAVEBIF endif findnext bifname endwhile Intellicomm v2.01 SCRIPT.DOC 142 SAVEINI__________________________________________________________________ SUMMARY SAVEINI [sINI_NAME] DESCRIPTION This advanced script command saves the currently loaded INI (main setup variables) information to disk. If sINI_NAME is omitted, $INI_NAME (the current main setup file) is assumed. Only a filename (CUSTOM, SOMEINI, etc) is required if sINI_NAME is specified. You may specify a D:\PATH and extension if necessary (i.e. if you used FINDFIRST/FINDNEXT to locate various INI filenames) but SAVEINI always always saves in $HOME_DIR (which cannot be modified) using the extension .INI. NOTE 1: Don't use SAVEINI unless you fully understand the LOADINI command and Main Setup Variables. SAVEINI is meant to be used after you modify one or more Main Setup Variables, and you wish to save the modified information to disk. NOTE 2: If sINI_NAME is specified and an INI already exists using the same filename, the existing .INI will be overwritten! You can use the EXIST or FINDFIRST command to see if a given .INI file already exists: variable ininame "CUSTOM" variable temp assign temp $HOME_DIR ininame notexist temp SAVEINI ininame ERRORLEVEL 0 SAVEINI successful. 1 SAVEINI unsuccessful (disk write error, invalid sINI_NAME, disk full). SEE ALSO LOADINI EXAMPLE ;Could be used to automatically change information in all .INI ; files. This example changes your home telephone number (User ; Settings screen). variable ini_name $HOME_DIR "*.INI" variable v findfirst ini_name ini_name ;store the first Ini in 'ini_name' Intellicomm v2.01 SCRIPT.DOC 143 while $errorlevel = 0 loadini ini_name assign *uhphn "555-555-1234" SAVEINI ini_name findnext ini_name endwhile SCAPTURE_________________________________________________________________ SUMMARY SCAPTURE [sFILENAME] ... DESCRIPTION Saves the contents of the screen to the file sFILENAME. If sFILENAME is omitted, the default Screen Capture Filename (*scap; defined on the main setup Filenames and Path screen) is assumed. If sFILENAME is specified but no D:\PATH is given, the file is saved in the current directory. NOTE: SCAPTURE always adds to the end of files. It never overwrites files. If you want to overwrite, simply DELETE the existing file (if any) before you use SCAPTURE. SEE ALSO CAPTURE EXAMPLE send "some command" waitfor "some text" SCAPTURE send "^MG" hangup list *scap ;display the screen capture file SCREENBLANK______________________________________________________________ SCREENRESTORE____________________________________________________________ SUMMARY SCREENBLANK SCREENRESTORE DESCRIPTION SCREENBLANK activates the screen blanker, just as if the usual inactivity period defined by the user had elapsed. Note that if the user does not have the screen blanker enabled (Icom main setup, Screen/Color Settings), the SCREENBLANK command has no effect. There usually will be no need to use the SCREENBLANK command, since Intellicomm activates the screen blanker on its own (after the user- defined inactivity period) even when scripts are running. The exception Intellicomm v2.01 SCRIPT.DOC 144 to this is if you set $KEY_CHECK to 0 (zero) to do your own keystroke handling. If that's the case it'll be up to you to blank the screen using SCREENBLANK. SCREENRESTORE restores the screen (if blanked) as if the user had pressed a key. You should only use this command when you must get the user's attention for some reason (to print an error message or the like), and in most cases Intellicomm itself will automatically restore the screen when something 'new' happens. For example, if you use WNDOPEN, MSGWIND, BOX ... or MENUBAR, MENUBOXH, MENUBOXV, or BOXGETS/GETS, or after a file transfer completes, or if Icom prints its own error window, SCREENRESTORE will be called automatically. You'll only have to use it in rare cases. EXAMPLE variable old_key_check $KEY_CHECK ;save previous value assign $KEY_CHECK 0 ;keys are no longer checked by Icom SCREENRESTORE ;make sure this is displayed cls print "NOTE: Do not attempt to abort this file transfer!" delay 50 ;the user cannot abort the file transfer due to $KEY_CHECK 0 above ; and further, without doing key checking, Icom will not activate ; the screen blanker SCREENBLANK download "X" "IMPORTNT.FIL" ;SCREENRESTORE is called automatically after the transfer. It wouldn't ; hurt anything to call it again here, but... it's not necessary. assign $KEY_CHECK old_key_check ;restore previous value SCRIPT___________________________________________________________________ SUMMARY SCRIPT sSCRIPTNAME sPARAMETER ... DESCRIPTION Runs another script from within a script, then continues running the previous script at the next line after the SCRIPT command. sSCRIPTNAME is the name of the script to run. Any parameters that follow the script name are placed in the GlobalStr array (see the 'Global Variables' section in SCRTUTOR.DOC) for use in the called script. If both sSCRIPTNAME and sPARAMETER are omitted, the Script Manager is displayed allowing the user to select one or more scripts to Run. ERRORLEVEL Intellicomm v2.01 SCRIPT.DOC 145 0 sSCRIPTNAME loaded and executed with no errors. Any other value in $ERRORLEVEL signifies an error loading the script or an error RETURN code from the called script. See the RETURN command for more details. SEE ALSO EXIT, RETURN EXAMPLE ;Execute POSTFILE.SCR on the file C:\ICOM\GET\ICOM201A.ZIP" SCRIPT "POSTFILE.SCR" "ICOM201" ".ZIP" "C:\ICOM\GET\ICOM201A.ZIP" SCROLL___________________________________________________________________ SUMMARY SCROLL nX1 nY1 nX2 nY2 nMODE nCOLOR DESCRIPTION Scrolls or clears an area of the screen. nX1 nY1 specify the top corner, nX2, nY2 specify the bottom corner ('X' is a screen column number from left to right, 'Y' is a screen row number from top to bottom. 1 1 is the top corner of the screen, $SCRN_WIDTH, $SCRN_HEIGHT [normally 80, 25] is the bottom corner of the screen). Screen windows set with the WINDOW or WNDOPEN command are ignored by SCROLL, meaning that 1 1 is always the same (the top corner of the screen), regardless of whether a WINDOW is set. nMODE tells SCROLL what to do. Positive numbers tell it to scroll the text UP, negative numbers tell it to scroll the text DOWN, zero tells it to simply clear the area. nCOLOR is the screen color used to fill in the scrolled (or cleared) area. For example if you scroll the screen up by one line, you'll then have a blank line where the bottom-most line used to be. nCOLOR tells SCROLL what color to set that bottom-most line to. Normally you'll use one of the $XXXX_COLOR System Variables such as $SCRN_COLOR, $TERM_COLOR or $NORM_COLOR. Please see the COLOR CODES Appendix for custom colors. SEE ALSO CLS EXAMPLE variable line 1 cls while line < $WND_BTM ;$WND_BTM accounts for the status line, if on print "Line " line Intellicomm v2.01 SCRIPT.DOC 146 endwhile pause "Press a key to scroll..." SCROLL 1 1 $SCRN_WIDTH $WND_BTM 1 $SCRN_COLOR SCROLLBACK_______________________________________________________________ SUMMARY SCROLLBACK DESCRIPTION Enters the Terminal's scrollback buffer (same as pressing [Alt-B] from Terminal Mode). This command was included mainly for use by Script Learn mode, and you probably won't have much use for it in your own scripts unless you turn $KEY_CHECK off. Normally you'll be better off letting Icom just process the hotkeys ([Alt-B], etc) itself. EXAMPLE See INKEY for an example of turning $KEY_CHECK off, and processing usual Icom hotkeys via script commands. SEND_____________________________________________________________________ SENDNC___________________________________________________________________ SENDNCP__________________________________________________________________ SENDNP___________________________________________________________________ SUMMARY SEND [sDATA ...] SENDNC sDATA ... SENDNCP sDATA ... SENDNP [sDATA ...] DESCRIPTION All send sDATA (one or more constant strings/numbers, or variables) out the current COM port ($COM_PORT). SEND and SENDNP add a Carriage Return (CR; same as pressing [Enter]) after sSDATA; while SENDNC (NC for 'N'o 'C'R) and SENDNCP do not. Further, SEND and SENDNC delay the sending of sDATA for the duration of the "Response Delay" item defined in BIF screen 1, if the modem is connected and a BIF is in use. The 'NP' variations SENDNCP and SENDNP (NP for 'N'o 'P'ause) do not. Control characters can be specified in sDATA in the usual manner, by preceding the character with a caret (^) (see SCRTUTOR.DOC and the ASCII CODES appendix). Further, a tilde (~) causes a 1 second delay in the sending of sDATA; usually to slow the command down to let the BBS (or modem) catch up. Intellicomm v2.01 SCRIPT.DOC 147 As mentioned above, by default both SEND and SENDNP add a carriage return (CR) after sDATA, which is the same as pressing [Enter] on your keyboard. But you can control this by modifying the $SEND_CR System Variable. On some BBS's, you don't want a CR to follow the command (if BBS "hotkeys" are in use), while on others you must enter the command with a CR. Rather than re-writing your scripts and changing SEND to SENDNC (send with no CR) or vice versa, you can stick with SEND in all your scripts and control whether a CR is added or not by changing the $SEND_CR System Variable at the top of the script. If $SEND_CR is non- zero, a CR is added by SEND/SENDNP. If $SEND_CR is zero, no CR is added. $SEND_CR can also be handy in making your scripts more user-friendly. You can tell SEND whether to add a CR or not by checking the BIF "CR w/Commands?" item on BIF screen 1: if *[G]adcr = "Yes" ;Add CR? [G] = BIF [G]eneral section (scrn 1) assign $SEND_CR 1 ;SEND/SENDNP add carriage returns else assign $SEND_CR 0 ;SEND/SENDNP don't add CR's endif With the above in place at the top of a script the user could simply modify the BIF to get the script to operate differently. NOTE: If you're dealing with BIF information (BIF variables) in your script; instead of using SEND to send BIF responses/commands, you should instead use SENDBIF, which interprets the special BIF command characters: @ = Run another script & = Execute a single script command ! = Execute a DOS command SEE ALSO $SEND_CR SEND EXAMPLE SEND "D^M~NICECAR.GIF^M~Z" ;Translation: ; [D]ownload ([Enter] and a 1 second pause) ; NICECAR.GIF ([Enter] and a 1 second pause) ; [Z]modem ([Enter] added by SEND) delay 30 download "Z" SENDNC EXAMPLE variable UserName Intellicomm v2.01 SCRIPT.DOC 148 SENDNC "Please enter your name: " cgets UserName 50 "^M" 60 send "^M^JWelcome, " UserName "." SENDBIF__________________________________________________________________ SUMMARY SENDBIF sSECTION sTAG DESCRIPTION SENDBIF is used to handle BIF responses, and it usually sends one or more commands to the BBS. It calls the same routine that Intellicomm itself calls to handle BIF responses, when a BIF prompt is found. I.e. you will only want to use it when you're certain a BIF has been properly set up. sSECTION is the BIF section, sTAG is the four letter tag of a specific item within a section. The BIF Variables section outlines all BIF sections and tags. If you use SENDBIF in your scripts (as opposed to regular SEND), you'll be able to control what your scripts send, and how that data it sent, directly from the BIF, instead of having to modify your script directly. SENDBIF supports the following special characters: ^ A tilde is used to specify a control charater (^M is [Enter], ^[ is [Esc], etc. See the ASCII CODES Appendix). ~ Causes a one second delay. Further, it supports the special command characters permitted in BIF responses: @SCRIPTNAME = Run another script &COMMAND = Execute a single script command !COMMAND = Execute a DOS command And both the Response Delay and BS Protection (BIF screen 1) are also supported by SENDBIF. The Response Delay allows you to pause SENDBIF for a specified length of time (in tenths of a second) before sending the sDATA parameter, and this can be handy on BBS's that flush their input buffers after displaying prompts. The BS Protection (Backspace Protection) item allows you to have SENDBIF send a specified number of Backspace characters to the BBS, after the Response Delay, to eliminate line noise before sending the proper response. SEE ALSO SEND EXAMPLE Intellicomm v2.01 SCRIPT.DOC 149 Please see the REDIAL example. SENDKEY__________________________________________________________________ SUMMARY SENDKEY sKEY ... DESCRIPTION SENDKEY allows you to send one or more keystrokes to the Icom terminal key handler. The key codes sent via SENDKEY look no different to Intellicomm than had you pressed the key(s) at the keyboard. You may specify up to 128 keys all with one SENDKEY command. The 'key' parameter(s) can be either a text string in quotes: SENDKEY "Send this" ;puts nine keys into the key queue and/or an extended key code, as outlined in the KEY CODES Appendix: SENDKEY 7936 ;puts a single extended key code in the queue SENDKEY converts the keycode differently depending on whether the sKEY parameter is in quotes or not. If you use this: SENDKEY "15104" ;15104 is the keycode for the [F1] key it will NOT translate to extended keycode 15104. Due to the quotes, it will be processed as five separate keystrokes: 1, 5, 1, 0, and 4. If you use this: SENDKEY 15104 ;no quotes all five characters are converted to a single number (extended keycode 15104; the [F1] key). If you specify more than one 'key' parameter, each must be separated by at least one space or TAB character as with all script parameters. If a sKEY parameter is an Icom terminal hotkey such as [F1] (help) [Alt- Z] (terminal menu), [Alt-D] (change to the BBS/Dialing Directory), etc., then it pops up the appropriate Icom menu or carries out whatever task the hotkey would if you pressed the key from terminal mode. This is where it can be useful to stack several key codes with a single SENDKEY command, since it allows you to operate WITHIN the menu after it opens (see the example below). However, if 'doorway mode' is on, the extended keycode(s) are simply sent to the BBS (see the $DOORWAY System Variable) no differently than if you pressed the key with doorway mode on. To send extended keycodes to the BBS instead of having Icom process it as a hotkey, simply turn doorway mode on: variable old_doorway $DOORWAY ;save the old doorway mode status assign $DOORWAY 1 ;1 turns doorway mode on SENDKEY 15104 ;send [F1] to the BBS instead of to Icom Intellicomm v2.01 SCRIPT.DOC 150 assign $DOORWAY old_doorway ;reset doorway mode to its previous state Doorway Mode is used by many BBS doors for extended keycode handling (i.e. use of real menus with hilight bars which allow [Up], [Down] to move the bar, etc). If you use a BBS door that supports Doorway Mode, you'll know what it is. If you don't, then Doorway Mode and sending extended keycodes to the BBS with SENDKEY is of no use to you. With doorway mode OFF you can have Icom actually perform tasks within menus you pop up, by stringing several keys together (similar to macros). However, SENDKEY has not been tested extensively for this use (it was included only for Script Learn mode, for oddball keycodes), so don't be surprised if you can't carry out an entire Intellicomm session with SENDKEY. See the EXAMPLE below for details of a semi-long SENDKEY example that does work. sKEY parameters (as with all Icom script parameters) may also be variables. If the contents of the variable contains only numbers, then it's the same as using a constant number (an extended keycode). If the contents of the variable contains one or more non-numeric characters, it's the same as specifying constant text in quotes. ERRORLEVEL 0 = Key(s) successfully queued. 1 = Keystroke queue full. You can send 128 keys at a time. If doorway mode is off and you specify one or more Icom hotkeys to carry out tasks, there is no way to tell whether the actual functions/tasks you requested were successful. If the keys are successfully queued, they are automatically processed. But since you can do literally anything with SENDKEY there's really no way for Icom to keep track of what occurred and set an errorlevel. You could cause Icom to process keystrokes for hours, carrying out myriad tasks with a single SENDKEY command. In such a case, as single errorlevel after the SENDKEY command finally finished, would be meaningless. If you're carrying out critical tasks you're better off using a regular script command which DOES set an errorlevel. For example, instead of sending the [Alt-D] extended keycode, a couple of 'T's to Tag a BIF or two, then 'D' to dial a BBS... use the DIAL command. Most Icom functions DO have script command equivalents (DIAL, FILEMAN [and COPY, DELETE, DISKSEARCH, etc.] HELP, HELPSEARCH, SCRIPT, and so forth) to allow you to carry out most of the common Icom tasks without using SENDKEY and looking up keycodes. Use SENDKEY only when you cannot accomplish the task with regular script commands, or when you want to send an extended keycode to the BBS (with doorway mode on). SEE ALSO $DOORWAY Also see the "SCRIPT COMMANDS AT A GLANCE" section to locate regular Intellicomm v2.01 SCRIPT.DOC 151 script commands which can be used with more reliability/control than using SENDKEY. EXAMPLE variable s ;define a variable called 's' ;pop a box up allowing up to 70 characters of input BOXGETS s 70 "SENDKEY Example" "Enter some text" SENDKEYS 7680 s 7936 "DEMOFILE.TXT^M^[" ;The above sends the [Alt-A] key (access the Editor) then sends the ; contents of variable 's' (whatever the user entered in the input ; box), then sends [Alt-S] (Save File), enters the filename ; DEMOFILE.TXT followed by ENTER (^M = CR) then presses [Esc] (^[ = ; ESC) to exit the editor. This would only work with the internal ; editor. SENDKEY does not send keys to external programs (it might in ; the future). SENDBREAK________________________________________________________________ SUMMARY SENDBREAK [nDURATION] DESCRIPTION Sends a break signal to the current COM port for nDURATION tenths of a second. If nDURATION is omitted, 30 tenths (3 seconds) is assumed which is the same duration used when [Ctrl-End] is pressed from Terminal mode. No messages are printed to the screen (as with [Ctrl-End] when SENDBREAK is called from a script. See the example if you want to notify the user that a break is being sent. SEE ALSO RXFLUSH, TXFLUSH EXAMPLE msgopen "Sending break" SENDBREAK msgclose SETCHR___________________________________________________________________ SUMMARY SETCHR vTARGETSTRING sCHARACTER nPOSITION DESCRIPTION Intellicomm v2.01 SCRIPT.DOC 152 Places character sCHARACTER into vTARGETSTRING at nPOSITION *overwriting* the existing character in vTARGETSTRING. Use STRINS to *insert* a character, without overwriting. For nPOSITION, 0 is the first character in vTARGETSYRING, 1 is the second, etc. A character must already exist in vTARGETSTRING at nPOSITION. SEE ALSO SETCHRS, STRINS EXAMPLE variable s "This is a string." SETCHR s "!" 16 ;changes character 16 (.) to ! SETCHR s "!" 17 ;does nothing: no character at position 17 to replace ; use STRCAT to add one or more characters. SETCHRS__________________________________________________________________ SUMMARY SETCHRS vTARGETSTRING sNEWSTRING nPOSITION [nNUMCHARS] DESCRIPTION Places nNUMCHARS of sNEWSTRING into into vTARGETSTRING at nPOSITION *overwriting* the existing portion of vTARGETSTRING. Use STRINS to *insert* a string, without overwriting. For nPOSITION, 0 is the first character in vTARGETSYRING, 1 is the second, etc. A string must already exist in vTARGETSTRING, and must be the same size or longer than sNEWSTRING. I.e. SETCHRS is designed to replace *existing* characters in vTARGETSTRING and not to add new characters to it. Use STRCAT, STRINS or STRSET to add to an existing string. SEE ALSO SETCHR, STRINS, STRSET EXAMPLE variable s "This is a string." SETCHRS s "replaced" 8 print s ;prints 'This is replaced.' variable s2 "IS A STRING." SETCHRS s s2 5 2 ;at position 5 in 's', only 2 chars from 's2' print s ;prints 'This IS replaced.' SETENV___________________________________________________________________ SUMMARY Intellicomm v2.01 SCRIPT.DOC 153 SETENV sENVSTRING ... DESCRIPTION Sets a new environment variable or clears an existing environment variable. Use the format "VARIABLE=setting" to either change an existing environment variable or to add a new variable. Use the format "VARIABLE=" (no new setting) to clear an existing environment variable. ERRORLEVEL 0 SETENV was successful. 1 SETENV was unsuccessful. SEE ALSO GETENV EXAMPLE variable path getenv path "PATH" strcat path ";C:\SOMEDIR" setenv "PATH=" path SETCOMM__________________________________________________________________ SUMMARY SETCOMM sPORT_SETTINGS ... DESCRIPTION Sets the current COM port ($COM_PORT) to the settings specified by sPORT_SETTINGS. sPORT_SETTINGS must be in the following format which is specified in one single parameter (spaces are ignored, but the commas [,] are mandatory): "BAUD, PARITY, DATABITS, STOPBITS" BAUD (the port speed or 'baud rate') must be one of the following: 300 1200 2400 4800 9600 19200 38400 57600 115200 PARITY must be one of the following (a single letter): Intellicomm v2.01 SCRIPT.DOC 154 N (No Parity) E (Even Parity) O (Odd Parity) DATABITS must be one of the following: 7 8 STOPBITS must be one of the following: 1 2 Any of the above items can be omitted, allowing you to change the Baud without changing the existing Parity, DataBits, StopBits, but the commas are mandatory whether an item is omitted or not. See the example for details. NOTE: The "..." after the sPORT_SETTINGS parameter means that you can specify multiple parameters which will be grouped together for you as a single parameter. This allows you to use multiple variables with a single SETCOMM command: variable baud "9600" variable parity "N" variable databits "8" variable stopbits "1" SETCOMM baud "," parity "," databits "," stopbits Note that the commas are still mandatory. ERRORLEVEL 0 Port settings changed to sPORT_SETTINGS 1 Unable to set port to sPORT_SETTINGS (not all combinations of data bits, stop bits and parity are supported by PC COM ports). SEE ALSO PORT, $COM_PORT, $COM_SPEED EXAMPLE SETCOMM "1200,N,8,1" ;1200 BAUD, No PARITY, 8 DATABITS, 1 STOPBIT SETCOMM "19200,,," ;set BAUD to 19200, leave PARITY, DATABITS, STOPBITS ; as is SETCOMM ",E,7,1" ;leave BAUD as is, set Even PARITY, 7 DATABITS, ; 1 STOPBIT Intellicomm v2.01 SCRIPT.DOC 155 SETCOMM ",N,," ;set PARITY to None, leave all others as is SHL______________________________________________________________________ SUMMARY SHL vRESULT nNUM nBITS DESCRIPTION Shifts nBITS bits in nNUM to the left and stores the result in vRESULT. SHL (SHift Left) is an advanced command for programmers. SEE ALSO SHR EXAMPLE variable result 1 SHL result result 1 print result ;prints 2 SHL result result 1 print result ;prints 4 SHL result result 2 print result ;prints 16 SHOWWHENS________________________________________________________________ SUMMARY SHOWWHENS DESCRIPTION Displays a screen that shows the current BBS prompts Intellicomm is tracking (either via script WHEN commands, or Intellicomm's automated routines), and the responses or script commands that will be executed when the prompt is found. Useful in debugging, to display the contents of WHEN slots. Note that you can also display this screen by pressing [Alt-W] (Show WHENs). SHR______________________________________________________________________ SUMMARY SHR vRESULT nNUM nBITS DESCRIPTION Shifts nBITS bits in nNUM to the right and stores the result in vRESULT. Intellicomm v2.01 SCRIPT.DOC 156 SHR (SHift Right) is an advanced command for programmers. SEE ALSO SHL EXAMPLE variable result 16 SHR result result 2 print result ;prints 4 SHR result result 1 print result ;prints 2 SHR result result 1 print result ;prints 1 STAMP____________________________________________________________________ SUMMARY STAMP sCOMMENT ... DESCRIPTION Stamps sCOMMENT in the Usage Log (if open). SEE ALSO LOG, LOGCLOSE EXAMPLE variable waiting_for assign waiting_for "Some Text" waitfor waiting_for 120 error return error: STAMP "WAITFOR unable to find text '" waiting_for "' ... hanging up." hangup STRBLANK_________________________________________________________________ SUMMARY STRBLANK vSTRING cCOMMAND DESCRIPTION Checks variable vSTRING to see if it is blank (empty or all whitespace). Intellicomm v2.01 SCRIPT.DOC 157 If vSTRING is blank, cCOMMAND is executed. If vSTRING is not blank (contains any characters other than spaces, tabs, carriage returns, line feeds, which are known as 'whitespace') cCOMMAND is skipped. SEE ALSO IF EXAMPLE variable input try_again: boxgets input 15 "Attention" "Please enter input" STRBLANK input goto try_again STRCHR___________________________________________________________________ STRCHRI__________________________________________________________________ SUMMARY STRCHR vPOSITION sSTRING sCHARACTER [nSTART_POSITION] DESCRIPTION Finds the first occurrance of sCHARACTER in string sSTRING. If sCHARACTER is found, its numeric position in sSTRING is stored in vPOSITION. If sCHARACTER is not found, -1 is stored in vPOSITION. nSTART_POSITION is an optional position in sSTRING to start the search at. If omitted, the search begins at the first character (0) in sSTRING. STRCHR is the case sensitive version. For example, if "a" is specified as sCHARACTER, it will not match "A" if found in sSTRING. STRCHRI is the case insensitive version. For example, if "a" is specified as sCHARACTER, it will match "A" if found in sSTRING. NOTE: String positions start at zero. The first character in sSTRING is 0, the second character is 1, etc. SEE ALSO STRRCHR, STRRCHRI, STRPOS, STRPOSI, SUBSTR STRCHR EXAMPLE variable s "This is a string." variable pos STRCHR pos s "." ;would store 16 in 'pos' Intellicomm v2.01 SCRIPT.DOC 158 if pos = -1 print "There is no period in '" s "'" else print "There is a period in '" s "'" print "at position: " pos print "But I'm going to get rid of it..." strdel s pos 1 ;a practical use for knowing the position of a given ; character in a string... endif STRCHR pos s "." ;this now stores -1 in 'pos' (no more periods) if pos > -1 ;greater than -1 is another way of checking... print "There are no more periods in this string: " s endif STRCHRI EXAMPLE variable s "This is a string." variable pos STRCHRI pos s "S" ;this stores 3 in 'pos' since the search is case ; insignificant, and an 's' exists at position 3 ; (remember, the first character is position 0) STRCPY___________________________________________________________________ SUMMARY STRCPY vTARGETSTR sSOURCESTR [nPOSITION] [nNUMCHARS] DESCRIPTION Copies nNUMCHARS characters from sSOURCESTR into vTARGETSTR at nPOSITION. If nPOSITION is omitted, 0 (first position in vTARGETSTR) is assumed. If nNUMCHARS is omitted all characters from sSOURCESTR are copied. STRCPY is similar to STRINS but it OVERWRITES existing characters in vTARGETSTR instead of pushing existing characters to the right. STRCPY is also similar to SETCHRS, but where SETCHRS will not truncate vTARGETSTR after nNUMCHARS characters have been copied: STRCPY *will* truncate vTARGETSTR after nNUMCHARS have been copied from sSOURCESTR. See the example for details. NOTE: String positions start at zero. The first character in vTARGETSTR is 0, the second character is 1, etc. SEE ALSO SETCHRS, STRINS, STRSET EXAMPLE Intellicomm v2.01 SCRIPT.DOC 159 variable s STRCPY s "ABCDEF" ;same as ASSIGN s "ABCDEF" STRCPY s "cd" 2 print s ;prints 'ABcd' (the original 'CD' at position 2 is ; overwritten, and the 'EF' that originally followed ; is truncated) STRDEL___________________________________________________________________ SUMMARY STRDEL vSTRING nPOSITION [nNUMCHARS] DESCRIPTION Deletes nNUMCHARS characters from vSTRING starting at nPOSITION. If nNUMCHARS is omitted, all characters from nPOSITION on are deleted. If nNUMCHARS is specified and more characters exist to the right of the deleted text, the characters are placed at nPOSITION. STRDEL works basically the same way that your word processor would work if you put the cursor under a given character on a line (nPOSITION) and pressed the [Delete] key one or more times (nNUMCHARS). If you omit nNUMCHARS a "Delete to end of line" (or end of string in this case) is performed. NOTE: String positions start at zero. The first character in vSTRING is 0, the second character is 1, etc. SEE ALSO STRINS, STRSET, STRREPLACE, STRREPLACEI, STRSTRIP, STRTRIM EXAMPLE variable s "Want this, don't want this, want this." variable pos variable num strchr pos s "," ;get position of first comma STRDEL s pos 1 ;kill the first comma strchr num s "," ;get position of second comma sub num pos ;this is how many characters to remove if we want ; to kill everything from 'pos' (originally the ; first comma) to the second comma. 'pos' must ; be subtracted from the position of the first ; comma to get the number of characters to remove STRDEL pos num print s ;prints 'Want this, want this.' STRINS___________________________________________________________________ Intellicomm v2.01 SCRIPT.DOC 160 SUMMARY STRINS vTARGETSTR sSOURCESTR [nPOSITION] [nNUMCHARS] DESCRIPTION Inserts nNUMCHARS characters from sSOURCESTR into vTARGETSTR at nPOSITION. If nPOSITION is omitted, 0 (first character in vTARGETSTR) is assumed. If nNUMCHARS is omitted the entire sSOURCESTR is inserted in vTARGETSTR at nPOSITION. NOTE 1: String positions start at zero. The first character in vSTRING is 0, the second character is 1, etc. NOTE 2: STRINS pushes existing characters in vTARGETSTR (from nPOSITION onward) to the right to make room for sSOURCESTR. It does not overwrite existing characters. If you want to overwrite existing characters in vTARGETSTR, use STRCPY (or STRREPLACE if appropriate). SEE ALSO STRCAT, STRCPY, STRDEL, STRREPLACE, STRREPLACEI EXAMPLE variable s STRINS s "STRINS text" "inserts " 7 print s ;prints 'STRINS inserts text' STRIPSLASH_______________________________________________________________ SUMMARY STRIPSLASH vSTRING DESCRIPTION Checks the end of string vSTRING for a trailing backslach (\) and removes it if one exists. STRIPSLASH is meant to be used mainly with directory names. EXCEPTION: If the character immediately to the left of the trailing slash is a colon (:) the trailing slash is NOT removed. In directory names, the backslash next to the drive specifier (C:\) is not a 'trailing' slash: it's the leading slash (root directory). Only trailing slashes are removed by STRIPSLASH. See example for details. SEE ALSO Intellicomm v2.01 SCRIPT.DOC 161 STRDEL, STRSTRIP, STRTRIM EXAMPLE variable s assign s "C:\" STRIPSLASH s prints ;prints 'C:\' (again, only trailing slashes are removed: ; and the slash next to the drive designator is not a ; trailing slash assign s "C:DIR\" STRIPSLASH s print s ;prints 'C:DIR' assign s "\DIR\" STRIPSLASH s ;prints '\DIR' STRITEM__________________________________________________________________ SUMMARY STRITEM vITEMBUFFER sSEARCHSTRING nITEMNUMBER [sITEMSEPARATOR] DESCRIPTION Searches sSEARCHSTRING for item number nITEMNUMBER and (if found) stores the item in variable vITEMBUFFER. If sITEMSEPARATOR is omitted, spaces, tabs and semicolons serve as the default item separator, and spaces/tabs enclosed between single or double quotes (' or ") in sSEARCHSTRING are ignored. If sITEMSEPARATOR is specified, spaces, tabs and semicolons are ignored and only sITEMSEPARATOR serves to separate one item from another in sSEARCHSTRING. ERRORLEVEL 0 Item number nITEMNUMBER was found in sSEARCHSTRING and was stored in vITEMBUFFER. 1 Item number nITEMNUMBER does not exist in sSEARCHSTRING. EXAMPLE ;In the first three examples, sITEMSEPARATOR is omitted causing ; STRITEM to use spaces and/or tabs and/or semicolons as the ; item separator; unless the space/tab/semicolon is between quotes. variable s "Item1 Item2 Item3 Item4" variable buf variable i STRITEM buf s 3 ;get item 3 from variable 's' Intellicomm v2.01 SCRIPT.DOC 162 print buf ;prints "Item3" (no quotes) assign s "'Item 1' 'Item 2' 'Item 3' 'Item 4'" STRITEM buf s 3 ;get item 3 from variable 's' print buf ;prints "Item 3" (no quotes) getenv s "PATH" ;get the DOS PATH print "Directories on your PATH:" assign i 1 ;start with item 1 while 1 getitem buf s i if $ERRORLEVEL > 0 break ;no more items print buf inc i ;i = i + 1 endwhile ;In the following example, sITENSEPARATOR is specified, causing ; STRITEM to ignore all characters other than the specified ; separator character: "^A" (Ctrl-A). This can be handy to create ; pseudo 'arrays' with strings.... just separator your array members ; with a control character such as ^A. assign s "Item;1^A Item;2 ^A Item;3" getitem buf s 2 print buf ;prints " Item;2 " (no quotes). I.e. all characters ; between the 1st and 2nd ^A are considered the 'item' getitem buf s 3 print buf ;prints " Item;3" (noting simply that a trailing ^A is ; NOT needed, but you can specify one if desired). STRLEN___________________________________________________________________ SUMMARY STRLEN vLENGTH sSTRING [nPOS] DESCRIPTION Stores the length of string sSTRING from nPOS onward in variable vLENGTH. If nPOS is omitted, 0 (the beginning of string sSTRING) is assumed. If nPOS is specified, STRLEN counts the number of characters from nPOS onwards. NOTE: String positions start at zero. The first character in sSTRING is 0, the second character is 1, etc. EXAMPLE variable s "12345" variable len STRLEN len s Intellicomm v2.01 SCRIPT.DOC 163 print len ;prints '5' STRLOWER_________________________________________________________________ SUMMARY STRLOWER vSTRING DESCRIPTION Converts all UPPERCASE characters in vSTRING to lowercase. SEE ALSO STRUPPER EXAMPLE variable s "THIS IS A STRING" STRLOWER s print s ;prints 'this is a string' STRCAT___________________________________________________________________ SUMMARY STRCAT vTARGETSTR sSOURCESTR ... DESCRIPTION Concatenates sSOURCESTR to vTARGETSTR (in English, it adds sSOURCESTR to the end of vTARGETSTR). SEE ALSO STRCPY, STRINS EXAMPLE variable dir1 "C:\DIR1" variable dir2 "C:\DIR2" strcat dir1 ";" dir2 print dir1 ;prints 'C:\DIR1;C:\DIR2' STRPAD___________________________________________________________________ SUMMARY STRPAD vSTRING sPADCHAR nNEWLENGTH DESCRIPTION Intellicomm v2.01 SCRIPT.DOC 164 Pads the left side of vSTRING with sPADCHAR to make it nNEWLENGTH characters long. sPADCHAR will normally be " " (a space) to pad a string to a given length for the purpose of lining things up on the screen (PRINT, so that everything is the same length; filenames for example) or writing them to a text file. SEE ALSO STRPADL, STRTRIM EXAMPLE 1 variable s "Pad me" STRPAD s "!" 6 print s ;prints 'Pad me' (no change since s is already 6 ; characters long) STRPAD s "!" 10 print s ;prints 'Pad me!!!!' EXAMPLE 2 variable f variable s fopen f "MYDATA.DAT" "w" boxgets s 30 "" "Enter Something" STRPAD s " " 30 ;make it 30 characters long, padding ; with spaces (which can be easily ; removed with STRTRIM) fputs f s ;write it to the file fclose f ;Padding data before writing it to a file is a common technique ; explained in "INTRODUCTION TO FILE INPUT/OUTPUT" in SCRTUTOR.DOC STRPADL__________________________________________________________________ SUMMARY STRPAD vSTRING sPADCHAR nNEWLENGTH DESCRIPTION Pads the right side of vSTRING with sPADCHAR to make it nNEWLENGTH characters long. sPADCHAR will normally be " " (a space) to pad a string to a given length for the purpose of lining things up on the screen (PRINT, so that everything is the same length; filenames for example) or writing them to a text file. STRPADL is most often used with numbers, to right justify them: 1 <-- Pad the left side with X number of spaces to line up 1234 Intellicomm v2.01 SCRIPT.DOC 165 12345 SEE ALSO STRPAD, STRLTRIM EXAMPLE 1 variable n1 "1" variable n2 "12" variable n3 "123" STRPAD n1 " " 5 STRPAD n2 " " 5 STRPAD n3 " " 5 print n1 ;prints ' 1' print n2 ;prints ' 12' print n3 ;prints ' 123' STRSET___________________________________________________________________ SUMMARY STRSET vTARGETSTR sCHAR nPOSITION nNUM DESCRIPTION Sets nNUM characters of vTARGETSTR to the character sCHAR at nPOSITION. STRSET is meant to be used to quickly set a string to a given character for drawing lines, or filling the screen with a given character, etc. See SCRDEMO.SCR for an example. STRSET is not meant to be used to overwrite the middle of a string with a given character: when it finishes writing the last sCHAR character it truncates vTARGETSTR right there. Use SETCHR to overwrite a portion of a string without truncating it. SEE ALSO SETCHR, SETCHRS EXAMPLE variable s STRSET s "▓" 0 70 ;fill 's' with 70 "▓" characters setchrs s " Hello! " 31 8 print s ;this prints: ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ Hello! ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ STRPOS___________________________________________________________________ Intellicomm v2.01 SCRIPT.DOC 166 SUMMARY STRPOS vPOSITION sSTRING sSEARCHSTR DESCRIPTION Searches string sSTRING for the string sSEARCHSTR. If found, the position of sSEARCHSTR in sSTRING is stored in the variable vPOSITION. If sSEARCHSTR is not found, vPOSITION is set to -1 (negative 1). Case is significant when searching for sSEARCHSTR: "ABC" will not match "abc" or "Abc". Use STRPOSI for a case insensitive search. NOTE: String positions start at zero. The first character in vSTRING is 0, the second character is 1, etc. SEE ALSO STRPOSI EXAMPLE variable s "ABCDEFGH" variable pos STRPOS pos s "DEF" ;this stores 3 in 'pos' if pos = -1 print "DEF does not exist." else print "DEF exists at position " pos endif STRPOSI__________________________________________________________________ SUMMARY STRPOSI vPOSITION sSTRING sSEARCHSTR DESCRIPTION Searches string sSTRING for the string sSEARCHSTR. If found, the position of sSEARCHSTR in sSTRING is stored in the variable vPOSITION. If sSEARCHSTR is not found, vPOSITION is set to -1 (negative 1). Case is insignificant when searching for sSEARCHSTR: "ABC" will match "abc" or "Abc". Use STRPOS for a case sensitive search. NOTE: String positions start at zero. The first character in vSTRING is 0, the second character is 1, etc. SEE ALSO STRPOS Intellicomm v2.01 SCRIPT.DOC 167 EXAMPLE variable s "ABCDEFGH" variable pos STRPOS pos s "def" ;this stores 3 in 'pos' if pos = -1 print "DEF does not exist." else print "DEF exists at position " pos endif STRRCHR__________________________________________________________________ STRRCHRI_________________________________________________________________ SUMMARY STRRCHR vPOSITION sSTRING sCHARACTER STRRCHRI vPOSITION sSTRING sCHARACTER DESCRIPTION Finds the *last* occurrance of sCHARACTER in sSTRING. If sCHARACTER is found, its numeric position in sSTRING is stored in variable vPOSITION. If sCHARACTER is not found, -1 is stored in vPOSITION. STRRCHR is the case sensitive version. For example, if "a" is specified as sCHARACTER, it will not match "A" if found in sSTRING. STRRCHRI is the case insensitive version. For example, if "a" is specified as sCHARACTER, it will match "A" if found in sSTRING. NOTE: String positions start at zero. The first character in sSTRING is 0, the second character is 1, etc. SEE ALSO STRCHR, STRCHRI, STRPOS, STRPOSI, SUBSTR STRRCHR EXAMPLE variable pos variable s "This is a string" variable s2 STRRCHR pos s " " ;finds the LAST space in variable 's' if pos = -1 print "No spaces exist in 's'" else inc pos ;pos = pos + 1 (get past the space) substr s2 s endif Intellicomm v2.01 SCRIPT.DOC 168 STRRCHRI EXAMPLE STRREPLACE_______________________________________________________________ STRREPLACEI______________________________________________________________ SUMMARY STRREPLACE vTARGETSTR sSEARCHSTR sREPLACESTR STRREPLACEI vTARGETSTR sSEARCHSTR sREPLACESTR DESCRIPTION Searches vTARGETSTR for all occurrances of sSEARCHSTR and replaces them with sSREPLACESTR. SRREPLACE is case sensitive (occurrances of "abc" will not replace occurrances of "ABC") while STRREPLACEI is case insensitive (occurrances of "abc" will replace occurrances of "ABC") SEE ALSO STRPOS, STRPOSI STRREPLACE EXAMPLE variable s "IBM XT" STRREPLACE s "xt" "486" print s ;prints 'IBM XT' (no change since STRREPLACE ; is case sensitive and "xt" doesn't match "XT" strreplace s "XT" "486" print s ;prints 'IBM 486' STRREPLACEI EXAMPLE variable s "IBM XT" STRREPLACEI s "xt" "486" print s ;prints 'IBM 486' STRSTRIP_________________________________________________________________ SUMMARY STRSTRIP vSTRING sCHAR DESCRIPTION Strips all occurrances of character sCHAR from string vSTRING. SEE ALSO STRDEL, STRTRIM Intellicomm v2.01 SCRIPT.DOC 169 EXAMPLE variable s "This is a string" STRSTRIP s " " ;strip all spaces print s ;prints 'Thisisastring' STRBTRIM_________________________________________________________________ STRLTRIM_________________________________________________________________ STRTRIM__________________________________________________________________ SUMMARY STRBTRIM vSTRING STRLTRIM vSTRING STRTRIM vSTRING DESCRIPTION The STRxTRIM commands are used to trim extra whitespace characters from string vSTRING. STRBTRIM trims whitespace from both sides of vSTRING. STRLTRIM trims whitespace only from the left side of vSTRING. STRTRIM trims whitespace only from the right side of vSTRING. ['Whitespace' includes spaces, tabs, carriage returns, line feeds and form feeds.] SEE ALSO STRDEL, STRSTRIP EXAMPLE variable s assign s " string data " STRBTRIM s print s ;prints 'string data' assign s " string data " STRLTRIM s print s ;prints 'string data ' assign s " string data " STRTRIM s print s ;prints ' string data' STRUPPER_________________________________________________________________ SUMMARY STRUPPER vSTRING Intellicomm v2.01 SCRIPT.DOC 170 DESCRIPTION Converts all lowercase characters in vSTRING to UPPERCASE. SEE ALSO STRLOWER EXAMPLE variable s "this is a string" STRUPPER s print s ;prints 'THIS IS A STRING' SUB______________________________________________________________________ SUMMARY SUB vREMAINDER nMINUEND nSUBTRAHEND DESCRIPTION Minuend and subtrahend? Well, that's what my old college math book says. <grin> SUBtracts nSUBTRAHEND from nMINUEND and stores the result in nREMAINDER. If you somehow forgot which number is called the 'subtrahend' and which is the 'minuend': 10 <-- Minuend - 5 <-- Subtrahend ---- 5 <-- Remainder (or Difference) We learn something new every day... SEE ALSO ADD, DIV, MUL, SUB EXAMPLE variable result SUB result 10 5 ;stores 10 - 5 (5) in variable 'result' print result SUBSTR___________________________________________________________________ SUMMARY SUBSTR vTARGET sSOURCE nPOSITION [nNUM] DESCRIPTION Copies nNUM characters from nPOSITION in string sSOURCE to variable vTARGET. If nNUM is specified, all characters from nNUM position in Intellicomm v2.01 SCRIPT.DOC 171 sSOURCE are counted. If nNUM is omitted, 0 (the beginning of sSOURCE) is assumed. NOTE: String positions start at zero. The first character in vSTRING is 0, the second character is 1, etc. SEE ALSO STRCPY EXAMPLE variable s SUBSTR s "This is a string!" 10 6 print s ;prints 'string' SWITCH___________________________________________________________________ CASE____________________________________________________________________ ENDCASE_________________________________________________________________ DEFAULT_________________________________________________________________ ENDSWITCH_______________________________________________________________ SUMMARY SWITCH vVARIABLE CASE [CASE] [...] cCOMMAND [cCOMMAND] [...] ENDCASE [CASE] [...] [cCOMMAND] [...] [ENDCASE] [DEFAULT] [cCOMMAND] [...] [ENDCASE] ENDSWITCH DESCRIPTION Compares the contents of vVARIABLE for equality to the CASE statement(s). If a match is found, the command(s) between the matching CASE/ENDCASE are executed. If no match is found, and a DEFAULT case is specified, the commands between DEFAULT/ENDCASE are executed. If no DEFAULT is specified and no matching CASE is found, all commands between SWITCH/ENDCASE are ignored. Intellicomm v2.01 SCRIPT.DOC 172 SWITCH is used when comparing many conditions (such as menu selections), where using IF/ELSE/ENDIF would be impractical. ERRORLEVEL SWITCH, ENDSWITCH, CASE, ENDCASE, DEFAULT do not change $ERRORLEVEL. SEE ALSO IF, WHILE NUMERIC SWITCH EXAMPLE menudefine "Option ~1" "Option ~2" "Option ~3" "e~Xit" menuboxv "Menu" "Select an option" SWITCH $MENUSELECTION CASE 1 ;is $MENUSELECTION equal to 1? print "Option 1 was selected." ;you can carry out any number of commands here before the ENDCASE ENDCASE CASE 2 ;is $MENUSELECTION equal to 2? print "Option 2 was selected." ENDCASE CASE 3 ;is $MENUSELECTION equal to 3? print "Option 3 was selected." ENDCASE DEFAULT print "[Esc] was pressed, or eXit was selected." ENDCASE ENDSWITCH STRING SWITCH EXAMPLE variable old_dir $CUR_DIR variable fname variable ext findfirst fname "*.*" while $ERRORLEVEL = 0 ;while a file is found fnstrip ext fname 15 ;get file .EXT (extension) SWITCH ext CASE ".ZIP" ;is 'ext' equal to ".ZIP" ? dos "PKZIP /v " fname ENDCASE CASE ".ARJ" ;is 'ext' equal to ".ARJ" ? dos "ARJ l " fname ENDCASE CASE ".LHA" ;is 'ext' equal to ".LHA" ? dos "LHA l " fname ENDCASE Intellicomm v2.01 SCRIPT.DOC 173 DEFAULT print fname " is not a .ZIP, .ARJ, or .LHA file." ENDCASE ENDSWITCH findnext fname endwhile SYSTEM___________________________________________________________________ SUMMARY SYSTEM [nHANGUP] [nERRORLEVEL] DESCRIPTION SYSTEM closes the current COM port (if open), closes all files, etc., hangs up/stays connected or asks the user what to do, then exits back to the 'caller'. The caller could be DOS, or a .BAT file, or a menu system (Windows, DESQview, etc): whatever called ICOM.EXE originally. nHANGUP is optional and can be either 1 (hangup unconditionally), or 2 (stay connected) or 0/any other number (or nothing) which causes SYSTEM to ask the user whether to disconnect, if connected. nERRORLEVEL is an optional error code which can be tested with the .BAT ERRORLEVEL statement. See the example for usage. SEE ALSO EXIT EXAMPLE send "SOME COMMAND" waitfor "Some BBS Prompt" 120 ERROR SYSTEM ;exit with no errorlevel, asking the user whether to ;disconnect or not (SYSTEM 0 0 does the same) ERROR: SYSTEM 1 1 ;hangup, exit to DOS with errorlevel set to 1 ;If you called a script like this from a .BAT file, you could test the ;ERRORLEVEL to see whether the script was successful or not: ; ; rem SOMEBAT.BAT ; ICOM.EXE /scr:MYSCRIPT.SCR ; if errorlevel 1 goto ERROR ; rem No errors, do whatever needs doing here ; :ERROR TAGGER___________________________________________________________________ SUMMARY Intellicomm v2.01 SCRIPT.DOC 174 TAGGER [sCATALOG] DESCRIPTION Enters the File Tagger. If sCATALOG is specified, the catalog is loaded for viewing. If sCATALOG is omitted, the NEWFILES catalog is loaded. NOTE: Control will not return to your script until the user exits the File Tagger. SEE ALSO DIAL, FILEMAN, SCRIPT EXAMPLE pause "Enter the File Tagger to Tag files for uploading..." TAGGER "FILELIST" TERMINAL_________________________________________________________________ SUMMARY TERMINAL DESCRIPTION TERMINAL is an advanced command that won't be needed by most script writers. If your script is having problems in that it doesn't display characters from the BBS and doesn't process keystrokes (i.e. [Alt-Z] to call up the Terminal menu), then TERMINAL will solve the problem. Otherwise, only read this if you're not faint-of-heart and are looking to conquer the entire script language. The TERMINAL command makes a call to Icom's "terminal handler", which is the Icom function that gets and handles characters from the COM port (if any), and processes user keystrokes and mouse clicks (if any). To make scripts easier to write, TERMINAL is automatically called for you in the following locations: + After a HANGUP command. + After a PORT command. + After a SEND, SENDNC, SENDNP, SENDNCP command. + After a SENDBIF command. + After a SETCOMM command. + Repeatedly during a WAITFOR command. + After a WAITUNTIL command. [During some other commands, such as UPLOAD and DOWNLOAD, the TERMINAL command is not used... but characters are still sent/received. All protocols deal directly with the COM port without going through the terminal.] WITHOUT this automatic use of the TERMINAL command, nothing from the BBS Intellicomm v2.01 SCRIPT.DOC 175 would ever be displayed on the screen while your script was running (characters would simply fill up Icom's internal receive buffer until flow control was activated). With Icom v1, before script 'loops' were introduced, it was almost impossible to run into a situation where Icom wouldn't call TERMINAL automatically through one script command or another, for longer than a millisecond or two. With the v2 script language it's possible to enter a WHILE loop and NEVER call the TERMINAL handler (depending on how long the loop executes for and what commands you execute in the loop). When in a loop, and not using any of the above commands which automatically call TERMINAL for you, do this if you want the terminal display to be updated in your loop: WHILE <condition> ;some valid WHILE condition TERMINAL ;call the TERMINAL handler ... ;then do whatever it is you're doing in the loop ENDWHILE ...or, if you don't use loops and still have problems, simply place a few TERMINAL commands randomly around your script until it works. *Each* TERMINAL command in your script will empty the entire Receive Buffer to the screen, and process any waiting keystrokes: both of which are buffered until they're handled by a call to TERMINAL. Another way to look at the TERMINAL command is that by NOT calling it, and by not using script commands that call it automatically (i.e. SEND, etc), you can PREVENT BBS characters from being displayed on the screen and can intercept keystrokes that would otherwise go to the Terminal handler (also see the $KEY_CHECK variable). You needn't worry about losing data from the BBS while you're not using TERMINAL... at least as long as you've got your "Flow Control" set up properly on your modem and in Icom ("Software flow control": XON/XOFF, etc., or "Hardware flow control": CTS/RTS, etc). Icom has a program called an "interrupt handler" that runs in the background, and is executed and driven entirely by the computer hardware (the COM port), to process incoming characters from the BBS. When a character is received from the modem, the COM port sends an interrupt, which in turn causes your processor to call Intellicomm's interrupt handler, which in turn places the character into Icom's internal "Receive Buffer" (the size is configurable in the main setup; it defaults to 4 Kbytes). When the receive buffer is about 80% full, Icom's interrupt handler activates "flow control", telling the modem (and the BBS) to STOP sending data, and this will happen whether you call TERMINAL or not. [Sometimes it takes a second or two for the BBS to stop sending, and that's why flow control is activated when the buffer is 80% full instead of waiting until it's ready to overflow.] The characters in the Receive Buffer (and keystrokes/mouse clicks in the keystroke buffer) simply won't be displayed to the screen or acted upon... they'll sit in the Receive Buffer waiting for you to call TERMINAL. EXAMPLE variable key ;define a variable to hold keystrokes variable old_kcheck $KEY_CHECK Intellicomm v2.01 SCRIPT.DOC 176 assign $KEY_CHECK 0 ;shut off the Terminal's keystroke handler msgopen "I'm not doing anything until you press [Esc]!" ;since there is no TERMINAL command in this loop, and ;since INKEY doesn't call TERMINAL automatically, nothing ;from the BBS is displayed on the screen, and no keystrokes ;(other than ESC) are processed. Total control... WHILE key <> "^[" ;while key is not equal to the ESC key inkey key ENDWHILE msgclose assign $KEY_CHECK old_kcheck TERMINAL ;kaboom, all characters received from the modem ; during the pause are now displayed rapidly Alternatively, instead of calling TERMINAL, you could also use CGETC and process characters one at a time in a loop. TIMER____________________________________________________________________ SUMMARY TIMER [nTENTHS] DESCRIPTION Starts a timer that will expire in nTENTHS of a second. Use TIMEUP to determine whether the timer has expired. Multiple calls to TIMER cancels the previous TIMER command (if any). If nTENTHS is zero or omitted, the timer never expires (until the script ends). SEE ALSO TIMERTOTAL, TIMEUP EXAMPLE TIMER 100 ;100 tenths (10 seconds) msgopen "Waiting 10 seconds..." while 1 timeup break endwhile msgclose TIMERTOTAL_______________________________________________________________ SUMMARY Intellicomm v2.01 SCRIPT.DOC 177 TIMERTOTAL vTOTAL DESCRIPTION Stores in vTOTAL the total tenths of a second that have elapsed since the last TIMER command. SEE ALSO TIMER, TIMEUP EXAMPLE variable total cls timer while 1 timertotal total printraw 1 1 $SCRN_COLOR "TIMERTOTAL: " total if total > 100 break ;break after 10 seconds endwhile TIMEUP___________________________________________________________________ SUMMARY TIMEUP cCOMMAND DESCRIPTION If the last timer started with the TIMER command has expired, cCOMMAND is executed. If the timer has not expired, cCOMMAND is skipped. SEE ALSO TIMER, TIMERTOTAL EXAMPLE timer 100 ;100 tenths (10 seconds) msgopen "Waiting 10 seconds..." while 1 TIMEUP break endwhile msgclose TONE_____________________________________________________________________ SUMMARY TONE nFREQUENCY nDURATION Intellicomm v2.01 SCRIPT.DOC 178 DESCRIPTION Sounds a tone of nFREQUENCY for nDURATION tenths of a second on the PC Speaker. The higher the number is for nFREQUENCY, the higher the sound is. The following list of numbers can be used as a reference for nFREQUENCY. Though the list does not contain all possible frequencies, it should get you started and allow experimentation: 247 B 262 C 277 C# (# = sharp) 294 D 311 D# 330 E 349 F 370 F# 392 G 415 G# 440 A 466 A# 494 B 523 Middle C 554 C# 587 D 622 D# 659 E 698 F 740 F# 784 G 880 A 988 B 1046 C 1175 D 1319 E 1397 F 1568 G 1760 A 1976 B SEE ALSO ALARM, BEEP EXAMPLE TONE 440 10 ;A delaync 1 ;staccato (distinctive notes that don't blend) TONE 494 10 ;B delaync 1 TONE 523 10 ;C TXFLUSH__________________________________________________________________ SUMMARY Intellicomm v2.01 SCRIPT.DOC 179 TXFLUSH DESCRIPTION Clears (flushes) the COM port Transmit Buffer. Characters sent to the modem using SEND, SENDNC, SENDBIF, etc., are not transmitted immediately: they are placed in a Transmit Buffer until the modem is ready to accept the characters. Use TXFLUSH to clear this buffer if necessary. SEE ALSO RXFLUSH UPDATEDNDX_______________________________________________________________ SUMMARY UPDATEDNDX DESCRIPTION Uploades the DOWNLOAD.NDX (same as selecting Tools | Update DOWNLOAD.NDX from the File Tagger). 'Update' means that all directories the user has defined in the main setup 'DOWNLOAD.NDX Directories' item will be scanned, and all files in these directories that do not exist in the DOWNLOAD.NDX index will be added. This is how Intellicomm keeps track of files you've downloaded, and On new files imports and automated downloads, Tagger ignores filenames that exist in the DOWNLOAD.NDX. EXAMPLE waitfor "Begin your download..." download "Z" UPDATEDNDX UPLOAD___________________________________________________________________ SUMMARY UPLOAD sPROTOCOL sFILENAME1 [sFILENAME2 ...] DESCRIPTION Uploads sFILENAME1 and [sFILENAME 2 ...] if specified using transfer protocol sPROTOCOL. sFILENAME1 is required by all protocols and may be a filename (FILENAME.EXT) or an explicit file and path (D:\PATH\FILENAME.EXT). If a lone filename (no D: or \PATH\) is specified in any of the sFILENAME? parameters, UPLOAD searches: 1) The directories on the Upload PATH ($UL_PATH), defined in the main setup or the current BIF. Intellicomm v2.01 SCRIPT.DOC 180 2) The current Download Directory ($DL_DIR), defined in the main setup or the current BIF. 3) If *pathsch (main setup item "Use PATH to Locate Files") is non-zero, all directories on the DOS PATH are then searched if the file cannot be found in any of the directories above. Note that sFILENAME1 may also be specified as "@FILELIST", where @FILELIST is a 'list' of files. The contents of the file 'FILELIST' would contain one or more filenames to upload (again, each file on the list may include a D:\PATH\ if necessary), with each filename or filespec on a separate line. sFILENAME2 and beyond are only supported by the 'batch' protocols below which have an asterisk following their name. Further, batch protocols accept the DOS wildcard characters * and ? in any of the sFILENAMEn parameters, whether specified explicitly or via a @FILELIST. sPROTOCOL is the 'hotkey' used to select the protocol from the protocol menu from Terminal Mode (including external protocols, if any are installed): "A" = ASCII "R" = Relaxed Xmodem "X" = Xmodem "1" = Xmodem-1K "K" = Xmodem-1K-G "Y" = Ymodem* "G" = Ymodem-G* "Z" = Zmodem* NOTE: Ymodem, Ymodem-G and Zmodem are 'batch' transfer protocols. This means that they can upload several files using a single UPLOAD command. ERRORLEVEL 0 Transfer successful (if batch, all files were uploaded) 1 User abort ([Esc] pressed) 2 Connection lost 3 Remote (BBS protocol) cancelled 4 Disk read error 5 Bad external protocol (if called an external and not found) 6 Flow control error (activated by remote and not deactivated) 7 Miscellaneous protocol error (too many timeouts, NAKs, etc). SEE ALSO DOWNLOAD EXAMPLE 1 UPLOAD "1" "FILENAME.ZIP" ;Upload FILENAME.ZIP using Xmodem-1K EXAMPLE 2 Intellicomm v2.01 SCRIPT.DOC 181 ;Upload D:\FILE1.ZIP, C:\TEMP\FILE2.ZIP and FILE3.ZIP using Ymodem UPLOAD "Y" "D:\FILE1.ZIP" "C:\TEMP\FILE2.ZIP" "FILE3.ZIP" EXAMPLE 3 ;Example upload using a file list variable f ;used to hold the file handle (number) fopen f "UPLIST.$$$" "w" ;create a file called UPLIST.$$$, "w"rite mode fputs f "\DIR1\FILE1.ZIP" ;fputs writes \DIR1\FILE1.ZIP to the file fputs f "\DIR2\*.*" ;all files in \DIR2 fputs f "\DIR3\FILE?.*" ; ... etc fclose f ;close the file (important) UPLOAD "Z" "@UPLIST.$$$" ;@ tells the protocol to use a file list delete "UPLIST.$$$" ;delete the list VARIABLE_________________________________________________________________ SUMMARY VARIABLE vNAME DESCRIPTION Creates a variable called vNAME. SEE ALSO SCRTUTOR.DOC explains variables in detail. EXAMPLE VARIABLE my_variable VPUSH____________________________________________________________________ SUMMARY VPUSH [nX1] [nY1] [nX2] [nY2] DESCRIPTION Saves screen data (including colors) to an internal memory buffer for later restoration with VPOP. The parameters following VPUSH are optional screen coordinates which allow you to save a portion of the screen instead of saving the entire screen (the square brackets denote optional items; you must not use square brackets when specifying the parameters). nX1 is the top screen column (left to right) nY1 is the top screen row (top to bottom) nX2 is the ending screen colum and nY2 is the ending screen row. Intellicomm v2.01 SCRIPT.DOC 182 If you omit one or more of the screen coordinates, the screen limit is assumed. The limits for nX1, nY1 are 1, 1 (top screen corner) and the limits for nX2, nY2 are $SCRN_WIDTH, $SCRN_HEIGHT (System Variables which hold the current width and height of the screen). VPUSH does NOT observe the screen limits set by the WNDOPEN or WINDOW commands. No matter what the current WNDOPEN/WINDOW limits are, 1, 1 is always the TOP of the screen to VPUSH and $SCRN_WIDTH, $SCRN_HEIGHT (the total screen witdh and height) are the bottom of the screen. You may VPUSH up to sixteen (16) screens/portions of the screen with multiple VPUSH commands. To restore the screen data saved by the last VPUSH, use VPOP. ERRORLEVEL 0 Screen data saved. 1 Not enough memory was available to save the screen data. VPUSH must allocate 2 bytes of memory per screen character (one for the screen character, and one for the color), so if you save an 80 x 25 screen 4200 bytes of memory (about 4K) is required to save the data. SEE ALSO VPOP, WNDOPEN EXAMPLE VPUSH ;save the whole screen if $ERRORLEVEL = 1 goto no_memory ;if $ERRORLEVEL is equal to 1 cls pause "The screen was saved before clearing. Press a key to restore: " VPOP ;restore the screen VPUSH 10 10 70 16 ;save from 10,10 to 70,16 if $ERRORLEVEL = 1 goto no_memory box "Box Title" 10 10 70 16 printraw -1 -1 $NORM_COLOR "This text is centered on the screen in a box" pause VPOP return no_memory: print "Not enough memory was available to save screen data." pause "Please press a key... " exit VGETCHR__________________________________________________________________ SUMMARY VGETCHR vBUFFER DESCRIPTION Intellicomm v2.01 SCRIPT.DOC 183 Gets the character at the current cursor position, and stores it in vBUFFER. Color information is ignored. SEE ALSO VGETCHRS EXAMPLE variable c VGETCHR c print "The character at the current cursor position is '" c "'" VGETCHRS_________________________________________________________________ SUMMARY VGETCHRS vBUFFER nSCRN_X nSCRN_Y nNUMCHARS DESCRIPTION Gets nNUMCHARS characters from the video screen at nSCRN_X (x coordinate left to right) nSCRN_Y (y coordinate top to bottom) and stores the characters in vBUFFER. Screen color information is ignored. The screen coordinates nSCRN_X and nSCRN_Y are NOT relative to the current screen WINDOW: coordinates 1 1 are always the top left corner of the screen. Coordinates $SCRN_WIDTH $SCRN_HEIGHT (the current width and height of the screen; normally 80 25 or 80 rows by 25 columns) are the bottom right corner of the screen. This allows VGETCHRS to read video characters that are outside the screen WINDOW, such as characters on the Icom status line. VGETCHRS is mainly of use after a WAITFOR. For example if you wanted to check the remaining online time in a BBS prompt you could wait for the prompt then use VGETCHRS to get the online time from wherever it shows up on the prompt. See example 1 below. SEE ALSO VGETCHR EXAMPLE 1 ;This example gets the remaining online time from a BBS prompt. ; Different types of BBS software display the online time in ; different positions (or not at all) so any scripts you write ; along these lines will be reliant on a specific BBS or door type. ; ; For the example a standard PCBoard Main Menu prompt is assumed: Intellicomm v2.01 SCRIPT.DOC 184 ; ;(XXX min. left) Main Board Command? variable time_left waitfor "Command?" ;assumes not at the prompt yet... if ; the script is already AT the prompt ; this WAITFOR is unnecessary vgetchrs time_left 2 $SCRN_Y 3 ;column 2, current row, 3 characters add time_left time_left 0 ;this math operation, while it does ; nothing (adds zero) will get rid of any ; spaces or text. Also if the ; characters VGETCHRS got were not ; numbers at all, time_left will be ; equal to 0 (zero) after the math ; operation if time_left = 0 goto have_time ;Impossible, or we wouldn't be online. ; More than likely the BBS uses different ; prompt format. If this occurs your ; script might just assume that there ; is ample online time. if time_left > 30 goto have_time ;more than 30 minutes available ;less than 30 minutes is available... exit the script, logoff, hangup, ; whatever would suit the occasion exit have_time: ;30 minutes or more is available... do whatever you needed more than ; 30 minutes to do send "D SOMEFILE.ZIP Z" waitfor "(Ctrl-X)" download "Z" exit EXAMPLE 2 variable BBS variable H variable M variable old_stat $STAT_ON ;save status line state (on/off) ;Status line reference for example; numeric ruler shows the nSCRN_X ; coordinates of items on the status line ; Joe's BBS HH:MM | Script| 19200 N81| ICOM.CAP | ... ;1234567890123456789012345678901234567890123456789012345678901234 ... ; 1 2 3 4 5 6 offline return ;skip if not online assign $STAT_ON 1 ;make sure status line is on Intellicomm v2.01 SCRIPT.DOC 185 vgetchrs BBS 2 $SCRN_HEIGHT 20 ;Get 20 characters from column 2 vgetchrs H 23 $SCRN_HEIGHT 2 ;Get 2 characters from column 23 vgetchrs M 26 $SCRN_HEIGHT 2 ;Get 2 characters from column 26 assign $STAT_ON old_stat ;put it back the way it was (if off) msgopen "Connected to " BBS " for " H " hours and " M " minutes" inkeyw msgclose return VPOP_____________________________________________________________________ SUMMARY VPOP DESCRIPTION Restores the last screen saved with VPUSH. SEE ALSO VPUSH EXAMPLE VPUSH cls pause "The screen was saved before it was cleared... Press a key: " VPOP WAITFOR__________________________________________________________________ SUMMARY WAITFOR sTEXT [nTIMEOUT] [LABEL] DESCRIPTION WAITFOR pauses a script to wait for specific text from the COM port (modem or BBS) handling any text defined by WHEN commands while waiting (see WHEN below). sTEXT is the text to wait for, nTIMEOUT is an optional timeout in seconds (stop waiting after timeout), and LABEL is an optional label to GOTO if the text is not found within the timeout period. NOTE: Only the first twenty characters of sTEXT are tracked by WAITFOR. The sTEXT specified in a WAITFOR needn't be the 'end' of a BBS prompt, nor need it be a complete BBS prompt. nTIMEOUT is an optional timeout in seconds. If you specify a timeout, and sTEXT is not found within the timeout period, WAITFOR will either continue at the next script line when the timeout elapses (if LABEL is Intellicomm v2.01 SCRIPT.DOC 186 not specified) or will GOTO the optional LABEL if you specify it. If no timeout is specified WAITFOR waits indefinitely for the sTEXT. If you do not wish to GOTO a label if sTEXT is not found within the nTIMEOUT timeout, you may omit the LABEL parameter and simply use the $ERRORLEVEL (see below) to determine whether the text was found or not. ERRORLEVEL 0 nTEXT was found. 1 nTEXT was not found. This errorlevel can be of use if you do NOT specify a LABEL parameter to jump to. SEE ALSO WHEN EXAMPLE 1 WAITFOR "Main Menu?" ;wait indefinitely for the main menu ;script continues here if/when Main Menu? is found EXAMPLE 2 WAITFOR "Main Menu?" 5 ;wait 5 seconds for the main menu if $ERRORLEVEL = 1 gosub locate_position ;demonstrates how to use $ERRORLEVEL to use a command other than ; GOTO if the text is not found (assumes there is a subroutine in ; the script called 'locate_position:'. See the WHEN command for ; a real example of locating your position on the BBS. EXAMPLE 3 when ;clear all WHENs when "Name?" send "James Brown" when "Password?" send "mypassword" WAITFOR "Selection:" 120 NoMenu return NoMenu: hangup ;waits 2 minutes (120 seconds) for the prompt 'Selection:', handling ; a short logon with WHENs while waiting. If the Selection: prompt ; is found, the script returns (exits back to terminal mode). If ; the Selection: prompt is not found within 2 minutes, the script ; hangs up. WAITUNTIL________________________________________________________________ SUMMARY WAITUNTIL sTIME [sDAY] Intellicomm v2.01 SCRIPT.DOC 187 DESCRIPTION Displays a box menu allowing the user limited control, then pauses script execution until sTIME on sDAY. If sDAY is omitted, the day of the week is ignored and only sTIME applies. sTIME can be specified in military time (13:00 = 1:00pm) or am/pm time (1:00p = 13:00). sDAY, if specified can be "Anyday", "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday" or "Saturday" or a three letter abbreviation ("Sun", "Mon", etc). ERRORLEVEL None. The box menu displayed during a WAITUNTIL allows the user to abort the script. If 'Cancel' is selected by the user, the script simply ends. EXAMPLE WAITUNTIL "12:05a" "Sun" ;wait until Saturday night at 12:05 am. ; [technically Sunday morning... this ; is pointed out because people rarely ; think of 12:05am SATURDAY as being ; Sunday morning, but it is to WAITUNTIL ; and your computer] WHEN_____________________________________________________________________ SUMMARY WHEN [sTEXT] [cCOMMAND] DESCRIPTION WHEN defines BBS text to watch for (nTEXT) and a command to execute (cCOMMAND) if/when the text is found during a WAITFOR. Up to nineteen WHENs can be specified prior to a WAITFOR, to handle up to nineteen different BBS prompts while waiting. Note that sTEXT and cCOMMAND are specified as optional parameters above: if you omit both parameters all previously defined WHENs (if any) are cleared. NOTE: Only the first twenty characters of sTEXT are tracked. If you specify more than twenty characters, WHEN ignores the extra characters. sTEXT needn't be the 'end' of a BBS prompt, nor need it be a complete BBS prompt. You 'could' do this: WHEN "!" SEND "something" and Icom would SEND "something" every time an exclamation mark was found during a WAITFOR. The trick is to define enough of the BBS prompt that Intellicomm v2.01 SCRIPT.DOC 188 it doesn't conflict with other regular text from the BBS.... the above probably wouldn't be a good idea since exclamation marks can show up just about anywhere. And the reason most of the WHEN examples use the END of the BBS prompt as opposed to the beginning is that the command (normally SEND, to send a response to the prompt) is executed *immediately* after the text is found. If the BBS has some sort of "keyboard buffer flusher" to erase line noise after displaying prompts, your response to the prompt could be lost if it's sent prematurely. By defining the end of the BBS prompt in WHENs, including the trailing space on the prompt, you can be fairly sure that the BBS has flushed its input buffer already and won't erase your response. Further, there is usually some sort of punctuation at the END of a prompt (a question mark or colon or the like) which also helps to make the text "unique". For example, PCBoard asks for your password using the following prompt: Password (Dots will echo)? You 'could' get away with using: WHEN "password" send $PASSWORD But this has been done many times (in both BIFs and scripts), and has failed many times when the Sysop has an opening bulletin/news file that has the word "password" in it! On the other hand, if you use the END of the password prompt: WHEN "(Dots will echo)? " SEND $PASSWORD ...it's VERY unlikely that such text would show up anywhere else but at the password prompt, which is the only place you want your password sent. The same applies to the BBS prompts you define in your BIFs. The easiest way to use WHEN is with a SEND or GOTO command. If you want ease of use, SEND/GOTO commands in WHENs are the most straightforward route to go. SEND simply sends the response to the prompt defined by the WHEN, and GOTO cancels the WAITFOR and jumps to another area of the script. If you want more power and flexibility, and want to use GOSUBs and other commands in WHENs, read on. If you're handling complicated tasks with GOSUBs in WHEN commands, it's important to understand that you have nineteen WHENs to work with in TOTAL. Going to a subroutine, or even calling another script, does NOT give you another nineteen WHENs to work with. If you call WHEN more than nineteen times before clearing previous prompts with a lone WHEN comand, the first WHEN you defined is overwritten. I.e. it wraps around back to the beginning if you go past nineteen. As long as you understand this (Icom deals with the same limitation in its own automated routines which use the exact same routines WHEN uses) it's really a simple matter to use GOTOs instead of GOSUBs, clear all the WHENs in your subroutine/goto, then jump back up to re-define the original WHENs. Example: redefine_whens: ;label to get above the WHENs Intellicomm v2.01 SCRIPT.DOC 189 WHEN ;clear any existing WHENs WHEN "this" GOTO handle_this ;GOTO instead of GOSUB/RETURN ...etc. up to 18 more WAITFOR "some text" handle_this: WHEN ;clear the previous WHENs, start anew WHEN "that" SEND "cmd" ...etc. up to 18 more WAITFOR "something else" GOTO redefine_whens ;jump back up to the original when done ERRORLEVEL No errorlevel is set by WHEN, since it doesn't do anything until WAITFOR is active... and WAITFOR sets its own error. If you specify more than nineteen WHENs, the first WHEN is overwritten with no error. SEE ALSO WAITFOR EXAMPLE Please see above for advanced use, and see the Introduction to Scripts at the beginning of the SCRTUTOR.DOC for basic usage. WHILE____________________________________________________________________ BREAK___________________________________________________________________ CONTINUE________________________________________________________________ ENDWHILE________________________________________________________________ SUMMARY WHILE nNUM1 OPERATOR nNUM2 ;a numeric comparison cCOMMAND [cCOMMAND] ENDWHILE WHILE sSTR1 OPERATOR sSTR2 ;OR a string comparison cCOMMAND [cCOMMAND] ENDWHILE DESCRIPTION WHILE/ENDWHILE is much like IF/ENDIF, but where IF/ENDIF execute a set of commands once and only once if a given condition is true, WHILE executes a set of commands over and over again, WHILE a given condition is true. Intellicomm v2.01 SCRIPT.DOC 190 BREAK ----- The optional BREAK command is only valid *between* WHILE and ENDWHILE commands. BREAK forces the script processor to break from the loop (exit the loop and skip to the next command following ENDWHILE). BREAK is used for conditions that cannot be specified directly in the WHILE command. For example, you may have several numeric and/or string comparisons to perform in the WHILE loop (using SWITCH or IF, which are valid in WHILE loops). Instead of having to do this: WHILE i < 10 if i2 = 1 goto endloop ... ENDWHILE endloop: ...you'd use a BREAK instead: WHILE i < 10 if i2 = 1 BREAK ;exit loop if i2 is equal to 1 ... ENDWHILE The BREAK above does the same thing as the first 'goto endloop' example. You can get out of a loop either way, but BREAK is considered better programming practice. CONTINUE -------- The optional CONTINUE command is only valid *between* WHILE and ENDWHILE commands. CONTINUE forces the script processor to immediately jump back up to the WHILE statement. Instead of having to do this: toploop: WHILE i < 10 inc i if i2 = 1 goto toploop ... ENDWHILE ...you'd use a CONTINUE instead: WHILE i < 10 inc i if i2 = 1 CONTINUE ... ENDWHILE The CONTINUE above does the same thing as the first 'goto toploop' example. You can get back to the top of a loop either way, but CONTINUE is considered better programming practice. One thing to watch when you use CONTINUE, however, is that you make sure that your WHILE condition or variable is modified BEFORE you use the CONTINUE command. If you did this: Intellicomm v2.01 SCRIPT.DOC 191 WHILE i < 10 if i2 = 1 CONTINUE inc i ;don't increment 'i' AFTER the CONTINUE ... ENDWHILE and 'i2' was equal to 1 ... your script would hang, since variable 'i' would never be incremented, and thus 'i' would always be less than 10 (i < 10). Take care of your WHILE variables (INCrementing, DECrementing, assigning values to strings, etc) immediately following the WHILE command at the *top* of the loop rather than at the bottom near the ENDWHILE, and you won't have any problems with CONTINUE. Try to get into the habit of typing your WHILE loops like this: while somevariable > 1 ;or whatever the condition is dec somevariable ;put your primary modifier in at the top, just ; after you define your WHILE condition endwhile ;and add the ENDWHILE so you don't forget it ...and AFTER you have the WHILE/ENDWHILE and your key modifier set up, THEN go and fill the rest of the loop in between (between WHILE and DEC in the example above). ERRORLEVEL WHILE/BREAK/CONTINUE/ENDWHILE do not change $ERRORLEVEL. SEE ALSO SWITCH, IF EXAMPLE WINDOW___________________________________________________________________ SUMMARY WINDOW [nX1] [nY1] [nX2] [nY2] DESCRIPTION Sets the screen WINDOW. All text displayed to the screen with PRINT, PRINTNC or PAUSE as well as text received from the communications port, stays within the current WINDOW coordinates. nX1, nY1 is the top corner of the window (X1 is the screen column, right to left, Y1 is the screen row top to bottom) while nX2, nY2 is the bottom corner. If no screen coordinates follow WINDOW the window is set to the full screen. SEE ALSO WNDOPEN, WNDCLOSE EXAMPLE Intellicomm v2.01 SCRIPT.DOC 192 cls WINDOW 5 5 75 20 ;leaves 4 rows/columns around the Window on all sides WNDCLOSE_________________________________________________________________ SUMMARY WNDCLOSE DESCRIPTION Closes the last window opened with the WNDOPEN command (restores the previous contents of the video screen), restores the previous $SCRN_COLOR, cursor on/off status, and cursor coordinates. Basically puts everything back the way it was before the last WNDOPEN command. SEE ALSO WNDOPEN EXAMPLE wndopen "Courtesy of WNDOPEN" pause "Press a key to remove this window... WNDCLOSE WNDOPEN__________________________________________________________________ SUMMARY WNDOPEN [sTITLE] [nX1] [nY1] [nX2] [nY2] DESCRIPTION WNDOPEN first saves the screen area of the window you're opening (given screen X1, Y1, X2, Y2 coordinates), saves the current WINDOW coordinates, screen color and cursor x,y position, then uses BOX to display a window box with optional title, then uses the WINDOW command to set the current WINDOW within the box, then calls GOTOXY 1 1 to move the cursor to the top of the window. The process is reversed when WNDCLOSE is called. You can call WNDOPEN up to 16 times (open 16 different windows, overlapping or hiding previous windows) before calling WNDCLOSE. sTITLE is an optional title to display in the window border top left corner. nX1 nY1 specify the top left corner of the window, nX2 nY2 specify the bottom right corner of the window. [X is a screen column left to right, Y is a screen row top to bottom.] If nX1 or nY1 is omitted, 1 is assumed (top corner). If nX2 is omitted, $SCRN_WIDTH is assumed. If nY2 is omitted, $SCRN_HEIGHT is assumed. Intellicomm v2.01 SCRIPT.DOC 193 SEE ALSO BOX, WNDCLOSE EXAMPLE ;Please see SCRDEMO.SCR for a more detailed example of WNDOPEN/WNDCLOSE WNDOPEN "Courtesy of WNDOPEN" pause "Press a key to remove this window... wndclose XOR______________________________________________________________________ SUMMARY XOR vRESULT nNUM nBITMASK DESCRIPTION Performs a bitwise eXclusive OR on nNUM using nBITMASK and stores the result in variable vRESULT. Exclusive OR gets right down to the nitty grittys of how computers store numbers. You must understand the binary number system to understand XOR totally -- but you still can make use of it without understanding binary by simply following this tip: The exact same XOR can change a 1 to a 0, and a 0 to a 1. Why would you care about such things? Well, it's an effecient and simple way to handle "toggles". If you want something to toggle itself on or off, you simply do an XOR someflag someflag 1 on the variable (where 'someflag' is the variable you want to toggle), and it'll toggle the value of the variable to on or off (1 or 0) depending upon its current value. You can actually store many toggles in a single variable... since there are many bits in binary numbers that can be turned on/off with XOR. You can toggle each bit on or off using XOR, but unless you know binary well you should stick to "XOR v v 1" (XOR the variable with the number 1) to turn your toggle off or on. SEE ALSO AND, OR, SHL, SHR EXAMPLE variable mytoggle ;declare the toggle (starts at 0 by default) gosub switch_toggle ;sets 'mytoggle' to 1 gosub switch_toggle ;sets 'mytoggle' to 0 gosub switch_toggle ;sets it back to 1 return Intellicomm v2.01 SCRIPT.DOC 194 switch_toggle: XOR mytoggle mytoggle 1 ;changes 1 to 0, or 0 to 1 return Intellicomm v2.01 SCRIPT.DOC 195 APPENDIXES A. SYSTEM VARIABLES A.1 Introduction System Variables can be used in place of constant parameters with any script command that takes a parameter. They're used to increase flexibility in your scripts, to allow you to write scripts that can be used by others, and also to allow you to write scripts that will adapt to changes you make to your OWN Intellicomm setup in the future. If you write a script that does some work in your 'Message Directory', and you specify your existing message directory into your script (using a constant such as "C:\MYMSGDIR") to refer to the directory, then your script will fail if you later rename that directory and define a new one in the Icom main setup or BIF. By using the $MSG_DIR System Variable in your script, instead of specifying the value as a constant, the script adapts to changes when you make them. When you use a System Variable in a script command, it's up to you to make sure that the variable has some relevance to the parameter. If you try this: PRINTRAW $BAR_COLOR $BORDER_COLOR $BOLD_COLOR "Print this text" it won't make much sense; though you CAN get away with it if you try (PRINTRAW expects the first parm to be a screen column, the second to be a screen row, and only the THIRD parm to be a color). It would make more sense to use this: PRINTRAW $SCRN_X $SCRN_Y $TERM_COLOR "Print this text" No checks are made to ensure that you're using the "proper" System Variable for a given case, since there really is no such thing as using the "proper" variable for a given case. The whole idea behind scripts is to allow you to do the unexpected and expand the horizons. A.1.1 BIF and INI (main setup) Variables The System Variables outlined in this section do not cover all of the Icom system information available to you from a script: they cover only the most commonly used system information. You can access ANY Icom variables using BIF Variables, and Main Setup Variables. See the next two appendices below. A.1.2 Changing System Variables Do not CHANGE the value of any important system variables ($SCRN_X and $SCRN_Y are not considered important, unless the BBS is trying to display something on-screen at the time) unless you're sure about what you're doing. Many of the system variables are made available for informational purposes, and are not meant to be changed ($HOME_DIR, for example, cannot Intellicomm v2.01 SCRIPT.DOC 196 be changed, nor can $DATE or $TIME or some of the other variables that simply return information). The various COLOR variables and PROTOCOL / DIRECTORY variables can be changed, though if you change any of them in a script you change them globally (the new information is used everywhere in Intellicomm) for the duration of the Icom session; until Icom is removed from memory and re-loaded, or until another main setup file (or BIF, for some variables) is loaded. You can cause Intellicomm to malfunction by changing the contents of some of these System Variables, if you don't do it properly and if you don't restore the original value before your script ends. If you DO change any important variables in your scripts, make sure that you save the contents of the variable before changing it, then restore the contents when your script ends. Example: variable old_dl_dir $DL_DIR ;define 'old_dl_dir', put contents of ; original $DL_DIR variable in it. assign $DL_DIR "C:\MYDIR" ;change the Download Dir to a new directory ... ;main body of script here exit_script: ;a label you GOTO to exit the script assign $DL_DIR old_dl_dir exit A.1.3 READ ONLY System Variables To avoid problems in your scripts (and with Intellicomm in general) that may be very difficult to locate, some of the System Variables are read only. If you try to modify the value of these variables directly your script will abort with a "$VARIABLE_NAME is READ ONLY" error. If a variable is read only, then you can access the contents of the variable for informational purposes: variable myfile $HOME_DIR "MYFILE.EXT ;Using this, you'd end up with something like: ; C:\ICOM\MYFILE.EXT in 'myfile'. $HOME_DIR is the directory ; that ICOM.EXE is located in. But you cannot change the variable itself: assign $HOME_DIR "C:\SOMEDIR\" Some of the system directories CAN be changed, however. If you change any of the System Variables that specify directories ($MSG_DIR, $REP_DIR, etc) then Icom will add a slash to the end of the directory name if you forget to specify it in your script. ALL directory names must have a trailing slash, since Icom simply appends filenames to the directory when it needs a file from a given directory. You don't want this: C:\MYDIRMYFILE.EXT. You want this: C:\MYDIR\MYFILE.EXT. Thus all directories have a trailing slash in MEMORY. Sometimes directories are displayed without the trailing slash, and sometimes they're DEFINED without a trailing slash in the main setup/BIFs, but Icom automatically adds the slash when storing the variable in memory. EXCEPTION: The Intellicomm v2.01 SCRIPT.DOC 197 $UL_PATH (Upload PATH) System Variable simply contains a list of directories that Icom uses to locate files to upload, and these directories need not have a trailing slash (slashes are added when needed). A.2 System Variable Summary All System Variables are listed in alphabetical order below, with the variable name first, a description of the variable, then any special notes/warnings about using the variable. To see a quick listing of System Variables grouped by TOPIC, see the COMMANDS AT A GLANCE section. The COLOR variables contain a number that specifies both the foreground and background color. To create your own colors (to create custom foreground or background colors), see the COLOR CODES Appendix below. $ALARMS__________________________________________________________________ Determines whether alarms are heard. Intellicomm sounds an alarm after connecting and when file transfers complete. Also determines whether script ALARM commands are heard. $BAR_COLOR_______________________________________________________________ The color of menu hilight bars (currently hilighted item). $BBS_AREA________________________________________________________________ Read only. Of use only when you call a script via a job Custom Command/Run Script task, $BBS_AREA allows you to check which area of the BBS your script is located, when Icom turns control over: [L] = the BBS Main Menu [M] = the BBS Message Menu [F] = the BBS File Menu [B] = the BBS Time Bank Menu The information is presented in this format (between square brackets) to maintain compatibility with the NEWAREA command. See NEWAREA for details. $BETA_VERSION____________________________________________________________ The current beta version of Intellicomm (0 if a production release). $BIF_DIR_________________________________________________________________ The BIF Directory (where .BIF files are stored). $BIF_NAME________________________________________________________________ The name of the currently loaded BIF. Intellicomm v2.01 SCRIPT.DOC 198 $BOLD_COLOR______________________________________________________________ The standard bold text color. Used to hilight menu hotkeys, and to emphasize important information. The PRINT, PRINTNC, and PAUSE commands allow you to use $BOLD_COLOR by specifying ^B (Ctrl-B) in your print strings. Example: PRINT "This is normal. ^BThis is bold.^B" $BORDER_COLOR____________________________________________________________ The color of menu and box borders. Used by Intellicomm for all menus, boxes, etc., and also by the WNDOPEN, MSGWIND, MSGOPEN commands. $BSSWAP__________________________________________________________________ If set to zero, the backspace key sends a backspace character. If non- zero, the backspace key sends a DEL character. $CAP_NAME________________________________________________________________ The full D:\PATH\FILENAME.EXT of the capture log. $CAP_STAT________________________________________________________________ Read Only. This variable can only be changed by Icom (when it opens/closes the capture file), the user ([Alt-L] terminal key), or CAPTURE, CAPPAUSE, CAPCLOSE in a script. $CAREA_FLD_______________________________________________________________ The File Area of the currently loaded Tagger catalog record (CGETREC). Use NEWAREA $CAREA_FLD to change to the proper BBS file area to download the file. See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details on using the $Cxxxx_FLD variables. $CARRIER_________________________________________________________________ Reflects the state of the DCD signal (carrier detect) on the current $COM_PORT. If 0 (zero), the modem is reporting that it is offline (not connected). If non-zero the modem is reporting that is is online (connected). Unfortunately most modems do NOT report the carrier status properly when using the factory (default) settings. If your modem is reporting online all the time ($CARRIER <> 0 even when offline), the fix will be either adding an &C1 command to your Initialize Modem string in the Icom main setup (2400 baud modems and faster) or the flipping of a small switch on or inside the modem; usually switch #6 (1200 bauders and below). See "Common Questions & Answers" in the Icom online help for more information. $CAT_DIR_________________________________________________________________ Intellicomm v2.01 SCRIPT.DOC 199 The Catalog Directory, where Tagger catalogs are stored. $CAT_NAME________________________________________________________________ The name of the currently open Tagger catalog (if any). $CCDATE_FLD______________________________________________________________ The Catalog Date of the currently loaded Tagger catalog record (CGETREC). See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details on using the $Cxxxx_FLD variables. $CDAY_FLD________________________________________________________________ The Transfer Day of the currently loaded Tagger catalog record (CGETREC). 0 = Anyday, 1 = Sunday, 2 = Monday, 3 = Tuesday, 4 = Wednesday, 5 = Thursday, 6 = Friday, 7 = Saturday. Use $DOW to check the current day of the week. See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details on using the $Cxxxx_FLD variables. $CFDATE_FLD______________________________________________________________ The File Date of the currently loaded Tagger catalog record (CGETREC) in the format YYYYMMDD. Use CDATE2DATE to convert these dates to the usual MM/DD/YY style. See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details on using the $Cxxxx_FLD variables. $CFLAG_FLD_______________________________________________________________ The user-defineable 'flags' field for the currently loaded catalog record (CGETREC). $CFLAG_FLD is a general purpose flag in EACH catalog RECORD, that you can use as you see fit. The real length of the 'FLAGS' field (a new database field introduced in v2.01) is 5 bytes; you have access to one of these bytes from scripts (using $CFLAG_FLD) for anything you want. Icom uses the FLAGS field (a portion of it that cannot be accessed from scripts) to keep track of file transfer results and Stubborn Tags. Each time a filename is sent to the BBS during automated transfers, Icom increments a counter stored in the FLAGS field. If the counter goes past 3, Icom cancels the transfer (keeping the file tagged), which eliminates any possibility that the same filename will be entered over and over again forever due to bad BIF setup, errors, etc. When 'File not Found', 'No time', 'No bytes', 'Transfer Successful', etc. are received from the BBS, Icom makes another note in the flags field, storing 'C' to cancel the transfer (Untag the file), 'S' for a successful transfer, etc. If you write a script to perform auto downloads, you can put $CFLAG_FLD to the same use. Icom never touches or checks the contents of $CFLAG_FLD (the portion that scripts have access to) so you can use it as you see fit to keep track of anything that your scripts need to keep Intellicomm v2.01 SCRIPT.DOC 200 track of. The field is set to a blank space (" ") by default, and it's good practice to set it back that way when your script is done with it. Example: cgetrec 5 assign $CFLAG_FLD "A" ;"A" would signify some condition to you... ; maybe that you'd already tried to download ; the file, or that the record should be ; deleted or untagged, etc. cputrec Later, to check the flag: cgetrec 5 if $CFLAG_FLD = "A" return ;skip something if flag is set And when your script ends: cgetrec 5 assign $CFLAG_FLD " " ;clear the flag cputrec $CLOC_FLD________________________________________________________________ The BIF/Location of the currently loaded Tagger catalog record (CGETREC). Compare $CLOC_FLD to $BIF_NAME to see if the file is available for download on the current BBS (IF $CLOC_FLD = $BIF_NAME). See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details on using the $Cxxxx_FLD variables. $CNAME_FLD_______________________________________________________________ The Filename of the currently loaded Tagger catalog record (CGETREC). See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details on using the $Cxxxx_FLD variables. $COM_PORT________________________________________________________________ The current COM port (1 - 8). $CPRIORITY_FLD___________________________________________________________ The 'Transfer Priority' of the currently loaded catalog record (CGETREC). $CPRIORITY_FLD allows you to check or set the transfer priority of the current file. Example: cgetrec assign $CPRIORITY_FLD 10 ;set to priority 10 (100 is the default) cputrec This will only work on either Tagged or Noted files. Check $CTAG_FLD to see whether a file is 'T'agged or 'N'oted. When using the Tag Intellicomm v2.01 SCRIPT.DOC 201 Status/Location sort order (see CSETSORT in SCRTUTOR.DOC), files are sorted by Tag Status, Location, Download Priority (a number from 1-200, 1 being top priority), file Conference, Filename. I.e. all Tagged files for a given BBS are grouped together, with the highest priority file first, the next-highest second, etc. By simply using the Tag Status/Location index and using CGETREC, you'll get all the Tagged files in the proper order, according to the priorities the user has set. $COM_SPEED_______________________________________________________________ The current COM port speed (300-115200). $CREC_STAT_______________________________________________________________ The status of the currently loaded Tagger catalog record (CGETREC). "D" = Deleted, "A" = Active. See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details on using the $Cxxxx_FLD variables. $CSIZE_FLD_______________________________________________________________ The File Size of the currently loaded Tagger catalog record (CGETREC). See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details on using the $Cxxxx_FLD variables. $CSORT_DIR_______________________________________________________________ Read only. The sorting direction of the currently open catalog. 0 = Forward, 1 = Reversed. Use CSETSORT to change the sort direction. $CSORT_ORDER_____________________________________________________________ Read only. The sorting direction of the currently open catalog. 0 = Forward, 1 = Reversed. Use CSETSORT to change the sort direction. $CTAG_FLD________________________________________________________________ The Tag Status of the currently loaded Tagger catalog record (CGETREC). N = Noted, T = Tagged, U = Untagged. See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details on using the $Cxxxx_FLD variables. $CTOTAL__________________________________________________________________ Read only. The total number of records in the currently open Tagger catalog. $CVTOTAL_________________________________________________________________ Read only. The total number of records that are 'viewable' in the currently open Tagger catalog. $VIEW_DATE filters out catalog records that are older than a given date, so $CTOTAL and $CVTOTAL will often Intellicomm v2.01 SCRIPT.DOC 202 differ. ASSIGN $VIEW_DATE "19800101" to make all records 'viewable'. $CURDIR__________________________________________________________________ The current DOS drive and directory in the format D:\ or D:\PATH\ (a trailing slash always exists). $CURDRIVE________________________________________________________________ The current DOS disk drive, without the colon (A, B, C, etc). $DATE____________________________________________________________________ Read only. The current system date. $DATE is formatted according to the main setup options "Date Format" [*date] and "Date Separator" [*datesep or $DSEP] on the General Settings screen. $DAY_____________________________________________________________________ Read only. The current system day of month (1-31). $DL_DIR__________________________________________________________________ The current Download Directory. If the currently loaded BIF has a Download Dir defined (BIF File screen), $DL_DIR will be set to the BIF Directory. If no Download Dir is defined in the BIF, the main setup Download Directory is assumed (main setup, Filenames and Paths screen). $DL_PROTOCOL_____________________________________________________________ The 'Receive Files' protocol defined in the currently loaded BIF. $DL_PROTOCOL uses the same format for protocols (a single letter) that the DOWNLOAD command expects. Thus you can use DOWNLOAD $DL_PROTOCOL to download files using the protocol defined in the BIF. $DOORWAY_________________________________________________________________ The current status of Doorway Mode; 0 = Off, 1 = On. $DOW_____________________________________________________________________ The current day-of-week. 1 = Sunday, 2 = Monday, 3 = Tuesday, 4 = Wednesday, 5 = Thursday, 6 = Friday, 7 = Saturday. $DSEP____________________________________________________________________ The Date Separator character defined on the main setup General Settings screen. $ECHO____________________________________________________________________ Terminal 'echo' status; 0 = Off, 1 = On. When echo is on, characters typed on the keyboard are also printed to the screen. Intellicomm v2.01 SCRIPT.DOC 203 $ERRORLEVEL______________________________________________________________ Used to check the results of many script commands. See the ERRORLEVEL sections in the Detailed Command Summary section above. $FARCH___________________________________________________________________ Read only. The state of the file Archive attribute; + = On, - = Off. EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is found. $FDATE___________________________________________________________________ Read only. The file modification date in the format defined on the main setup General Settings screen (Date Format, Date Separator). EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is found. $FDAY____________________________________________________________________ Read only. The file modification date, day of month only (1-31). EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is found. $FHIDDEN_________________________________________________________________ Read only. The state of the file Hidden attribute; + = On, - = Off. FINDFIRST and FINDNEXT set this variable if the file is found (EXIST and NOTEXIT cannot find hidden files). $FHOUR___________________________________________________________________ Read only. The file modification time, hour only (0-23). EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is found. $FMIN____________________________________________________________________ Read only. The file modification time, minute only (0-59). EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is found. $FMONTH__________________________________________________________________ Read only. The file modification date, month only (1-12). EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is found. $FRDONLY_________________________________________________________________ Read only. The state of the file Read Only attribute; + = On, - = Off. EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is found. Intellicomm v2.01 SCRIPT.DOC 204 Files with the Read Only attribute set cannot be deleted or overwritten. $FSEC____________________________________________________________________ Read only. The file modification time, second only (0-59). EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is found. $FSIZE___________________________________________________________________ Read only. The file size. EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is found. $FSUBDIR_________________________________________________________________ Read only. The state of the Subdirectory attribute; + = On, - = Off. FINDFIRST and FINDNEXT set this variable if the file is found (EXIST and NOTEXIT cannot find subdirectories). If the Subdirectory attribute is set, the file is a subdirectory (these directory entries are marked with <DIR> in Icom's File Manager). $FSYSTEM_________________________________________________________________ Read only. The state of the System File attribute; + = On, - = Off. FINDFIRST and FINDNEXT set this variable if the file is found (EXIST and NOTEXIT cannot find System files). $FTIME___________________________________________________________________ Read only. The file modification time in the format defined on the main setup General Settings screen (Time Format, Time Separator). EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is found. $FVOLID__________________________________________________________________ Read only. The state of the Volume ID attribute; + = On, - = Off. FINDFIRST and FINDNEXT set this variable if the file is found (EXIST and NOTEXIT cannot find Volume ID's). Only one file per disk (in the root directory) has the Volume ID attribute set. $FULL_SCRIPT_NAME________________________________________________________ The full D:\PATH\FILENAME.EXT of the currently executing script. $FYEAR___________________________________________________________________ Read only. The file modification date, year only (1990, 1995, 2000, etc). EXIST, FINDFIRST, FINDNEXT, and NOTEXIST set this variable if the file is found. Intellicomm v2.01 SCRIPT.DOC 205 $HOME_DIR________________________________________________________________ The D:\PATH\ where ICOM.EXE and many of Intellicomm's data files reside. $HOME_DIR can be overridden with a SET ICOM=D:\PATH\ command (sets an environment variable) from the DOS prompt or AUTOEXEC.BAT file. $HOTKEY_1________________________________________________________________ $HOTKEY_2________________________________________________________________ $HOTKEY_3________________________________________________________________ $HOTKEY_4________________________________________________________________ $HOTKEY_5________________________________________________________________ Allows you to define up to 5 'hotkeys' for use with the GETS and BOXGETS commands. The hotkeys you define must be extended keycodes such as an [Alt] key combination ([Alt-A], [Alt-B], etc). See the KEYBOARD CODES appendix for appropriate key codes. Please see the BOXGETS command for an example of usage. $HOUR____________________________________________________________________ Read only. The current system time of day, hour only (0-23; 0 = Midnight). $HSEC____________________________________________________________________ Read only. The current system time of day, hundredth of a second only (0-99). $INI_NAME________________________________________________________________ The currently loaded .INI (main setup) file. $KEY_ALTQ________________________________________________________________ If set to 0 (zero), the script processor ignores [Alt-Q] keypresses which prevents the user from aborting the script. This can be useful when you have some important cleanup work to do before your script ends. If set to any number other than zero, [Alt-Q] pops up the Job/Script Control Menu. $KEY_CHECK_______________________________________________________________ If set to 0 (zero), the script processor doesn't check for any keys at all, effectively disabling all Intellicomm functions. You can then handle every keystroke as you see fit. For advanced script writers only. $KEY_FILTER______________________________________________________________ Allows you to define up to ten normal ASCII characters that BOXGETS, GETS, and GETSXY will not accept. For example, if you're prompting the Intellicomm v2.01 SCRIPT.DOC 206 user for a filename, and you don't want to accept wildcards (* and ?): assign $KEY_FILTER "*?" gets somevariable 8 ;GETS will not allow * or ? to be entered assign $KEY_FILTER "" ;restore to normal $LINEFEED________________________________________________________________ If set to 0 (zero), the Terminal does not add line feed characters when carriage returns are received from the COM port. If set to any number other than zero, line feeds are automatically added by the Terminal display routines whenever a carriage return is received. If lines from the BBS/modem overwrite one another, ASSIGN $LINEFEED 1. If lines from the BBS/modem are double-spaced, ASSIGN $LINEFEED 0. $LST_DIR_________________________________________________________________ The D:\PATH\ that BBS new files lists are captured to (automated jobs, "Get new files list" task). $MAJOR_VERSION___________________________________________________________ Read only. The major Intellicomm version number (2) to the left of the decimal point. $MENUSELECTION___________________________________________________________ Set to the menu item selected by MENUBAR, MENUBOXH and MENUBOXV. $MIN_____________________________________________________________________ Read only. The current system time of day, minute only (0-59). $MINOR_VERSION___________________________________________________________ Read only. The minor Intellicomm version number to the left of the decimal point. Intellicomm v2.01 has a $MINOR_VERSION of 1, v2.10 would have a minor version of 10 (ten), etc. $MONTH___________________________________________________________________ Read only. The current system date, month only (1-12; 1 = January). $MSG_DIR_________________________________________________________________ The current Message Directory (where message packets should be downloaded to). If the currently loaded BIF has a Message Dir defined (BIF Message screen), $MSG_DIR will be set to the BIF Directory. If no Message Dir is defined in the BIF, the main setup Message Directory is assumed (main setup, Filenames and Paths screen). NOTE: If your script downloads mail packets, it's up to you to do the following in order to get the packet into the proper directory: Intellicomm v2.01 SCRIPT.DOC 207 assign OldDLDir $DL_DIR ;save existing D/L Directory assign $DL_DIR $MSG_DIR ;now assign the message dir to the D/L dir download $MSG_PROTOCOL "" ;now downloads into the Message Directory assign $DL_DIR OldDLDir ;put it back the way it was $MSG_PROTOCOL____________________________________________________________ The 'Receive Mail' protocol defined in the currently loaded BIF. $MSG_PROTOCOL uses the same format for protocols (a single letter) that the DOWNLOAD command expects. Thus you can use DOWNLOAD $MSG_PROTOCOL to download mail packets using the protocol defined in the BIF. $NORM_COLOR______________________________________________________________ The color of normal text on all Intellicomm displays. $PASSWORD________________________________________________________________ The Logon Password defined in the currently loaded BIF. $OPSYSTYPE_______________________________________________________________ Allows you to determine which Operating System your script is running under: 0 = DOS, 1 = Windows, 2 = OS/2, 3 = DESQview. Example: switch $OPSYSTYPE case 0 print "DOS detected." endcase case 1 print "Windows v3.x detected." endcase case 2 print "OS/2 v2.x detected." endcase case 3 print "DESQview detected." endcase endswitch Windows versions lower than v3.00 and OS/2 versions lower than v2.0 are ignored and will be reported as DOS (0). $PRN_____________________________________________________________________ The printer device as defined on the main setup / Filenames and Paths screen (defaults to PRN). $REP_DIR_________________________________________________________________ The current Reply Directory (where message packets should be downloaded to). If the currently loaded BIF has a Reply Dir defined (BIF Message Intellicomm v2.01 SCRIPT.DOC 208 screen), $REP_DIR will be set to the BIF Directory. If no Reply Dir is defined in the BIF, the main setup Reply Directory is assumed (main setup, Filenames and Paths screen). NOTE: If your script uploads reply packets, it's up to you to specify the proper directory when you upload: upload $REP_PROTOCOL $REP_DIR "PACKET.REP" $REP_PROTOCOL____________________________________________________________ The 'Send Mail' protocol defined in the currently loaded BIF. $REP_PROTOCOL uses the same format for protocols (a single letter) that the UPLOAD command expects. Thus you can use UPLOAD $REP_PROTOCOL to upload mail packets using the protocol defined in the BIF. $RXCNT___________________________________________________________________ Reports the number of characters currently waiting in the communications Receive Buffer. $SCRIPT_DIR______________________________________________________________ The Script Directory (D:\PATH\ where Icom scripts are located). $SCRIPT_NAME_____________________________________________________________ The FILENAME.EXT (no D:\PATH\) of the currently executing script. Use $FULL_SCRIPT_NAME if you require the full D:\PATH\FILENAME.EXT. $SCRN_COLOR______________________________________________________________ The current screen color. Changing $SCRN_COLOR affects only NEW information printed on the screen. It does not change the color of EXISTING information on the screen. To display the entire screen in a new color, you must use CLS (clear screen) after changing $SCRN_COLOR. $SCRN_HEIGHT_____________________________________________________________ Read only. The total number of rows (lines top to bottom) available on the video display. 25 rows is the usual but EGA displays can also use 43 lines, and VGA displays can use 50 lines. $SCRN_WIDTH______________________________________________________________ Read only. The total number of columns (characters left to right) available on the video display. 80 columns is the usual. $SCRN_WRAP_______________________________________________________________ Determines whether the Terminal (and PRINT, PRINTNC, PAUSE commands) truncates or wraps lines that are longer than can fit in the current video display WINDOW. If $SCRN_WRAP is zero, lines are truncated at $WND_RIGHT (the right-most column of the current WINDOW). If $SCRN_WRAP Intellicomm v2.01 SCRIPT.DOC 209 is any number other than zero, lines wrapped to the next display line. Setting $SCRN_WRAP to 1 does not give you word processor type 'word wrapping'. Words will be split/wrapped to the next line right in the middle of a word if necessary. $SCRN_X__________________________________________________________________ Read only. The current X position (screen column, left to right) of the cursor. Use GOTOXY to change the cursor position. $SCRN_Y__________________________________________________________________ Read only. The current Y position (screen row, top to bottom) of the cursor. Use GOTOXY to change the cursor position. $SEC_____________________________________________________________________ Read only. The current system time of day, second only (0-59). $SEND_CR_________________________________________________________________ Determines whether the SEND, SENDNP, and SENDNPC commands add a carriage return to the text they send. If $SEND_CR is zero, no CR is added. Otherwise a CR is added. $SOUND___________________________________________________________________ Determines whether Intellicomm makes any sounds at all on the PC speaker. If $SOUND is zero, ^G (BELL) characters from the BBS are not heard, nor are alarms, nor do the script ALARM or BEEP commands make any sound. $STAT_COLOR______________________________________________________________ The color of the Terminal status line. $STAT_ON_________________________________________________________________ Holds the current display status of the Terminal Mode status line (all scripts execute from Terminal Mode). 0 = Off, 1 = On. You can also hide or unhide the status line by ASSIGNing 0 or 1 to this variable. Changing the state of this variable (ASSIGN $STAT_ON x) automatically resets $WND_BTM (the current WINDOW bottom screen line). Further if you previously used a WNDOPEN command $WND_BTM will *not* be set properly to reflect the new screen size when you call WNDCLOSE (WNDOPEN saves all $WND_* coordinates when you call it, and restores those same values when you call WNDCLOSE). Thus if you plan on using either the WINDOW or WNDOPEN commands in your script you should change $STAT_ON *first* or you will lose your current bottom window limit, and will not get the proper $WND_BTM when you call WNDCLOSE. Example: WNDOPEN "Box Title" 5 5 75 20 ;20 is the bottom screen row of the box PRINT $WND_BTM ;$WND_BTM is now 19 (20=box border) Intellicomm v2.01 SCRIPT.DOC 210 ASSIGN $STAT_ON 0 ;turn off the status line PRINT $WND_BTM ;$WND_BTM is now $SCRN_HEIGHT (the full ; height of the screen), not 19. PRINT ; would write over the bottom box border ; right to the end of the screen WNDCLOSE ;resets $WND_BTM to whatever value it ; was when WNDOPEN was called. I.e. ; the change in $STAT_ON is lost and ; though the status line will not be ; VISIBLE, the bottom screen line will ; not be used. ;this is the correct way to do it: ASSIGN $STAT_ON 0 ;turn off FIRST (resets $WND_BTM) WNDOPEN "Box Title" 5 5 75 20 ;$WND_BTM is now set to row 19 ; (20=window border), and WNDOPEN ; saved the proper $WND_BTM value. WNDCLOSE ;$WND_BTM is now reset to the proper ; value, since it was reset ; BEFORE the call to WNDOPEN $WND_BTM is also lost when you ASSIGN $STAT_ON 1 to turn the status line back on. Motto: if changing $STAT_ON, it is best done at the beginning and end of your scripts (unless you don't use any WNDOPEN or WINDOW commands... if that's the case it really doesn't matter). You should also save the old display status before changing $STAT_ON since as with most System Variables the value is NOT automatically restored when your script ends (you may want to leave it that way... Icom has no way of knowing): VARIABLE old_stat_on $STAT_ON ;define 'old_stat_on', store the value of ; $STAT_ON (0 or 1) in it. ASSIGN $STAT_ON 0 ;turn it off ... ;body of script here ASSIGN $STAT_ON old_stat_on ;restore original value $TERM_COLOR______________________________________________________________ The DEFAULT color of the terminal display (not the current color; $SCRN_COLOR holds the current color). $TIME____________________________________________________________________ Read only. The current system time. $TIME is formatted according to the main setup options "Time Format" [*time] and "Time Separator" [*timesep or $TSEP] on the General Settings screen. $TSEP____________________________________________________________________ The Time Separator character defined on the main setup General Settings screen. Intellicomm v2.01 SCRIPT.DOC 211 $TXCNT___________________________________________________________________ Reports the number of characters currently waiting in the communications Transmit Buffer. $UL_PATH_________________________________________________________________ The current Upload PATH. If the currently loaded BIF has an Upload PATH defined (BIF File screen), $UL_PATH will be set to the BIF path. If no Upload PATH is defined in the BIF, the main setup Upload PATH is assumed (main setup, Filenames and Paths screen). Directories on the Upload PATH are defined in the same manner as the regular DOS PATH: "C:\DIR1;C:\DIR2;C:\DIR3 ...etc" When UPLOAD is used, all directories in the Upload PATH are searched to locate the file(s) to upload. $UL_PROTOCOL_____________________________________________________________ The 'Send Files' protocol defined in the currently loaded BIF. $UL_PROTOCOL uses the same format for protocols (a single letter) that the UPLOAD command expects. Thus you can use UPLOAD $UL_PROTOCOL to upload files using the protocol defined in the BIF. $VIEW_DATE_______________________________________________________________ The View Date of the currently open catalog. Any catalog records with a Catalog Date ($CCDATE_FLD) older than $VIEW_DATE are ignored, and will not be returned by CGETREC. ASSIGN $VIEW_DATE "19800101" (January 1st, 1980) to disable the $VIEW_DATE feature. See "INTRODUCTION TO DATABASE COMMANDS" in SCRTUTOR.DOC for more details on using the $VIEW_DATE variable. $WND_BTM_________________________________________________________________ The bottom video row of the current WINDOW. $WND_HEIGHT______________________________________________________________ The total number of screen rows (top to bottom) in the current WINDOW. $WND_LEFT________________________________________________________________ The left-most video column of the current WINDOW. $WND_RIGHT_______________________________________________________________ The right-most video column of the current WINDOW. $WND_TOP_________________________________________________________________ Intellicomm v2.01 SCRIPT.DOC 212 The top video row of the current WINDOW. $WND_WIDTH_______________________________________________________________ The total number of screen columns (left to right) in the current WINDOW. $YEAR____________________________________________________________________ Read only. The current system date, year only. Intellicomm v2.01 SCRIPT.DOC 213 B. BIF VARIABLES (Advanced Users Only) BIF Variables allow you to access every configurable item in any BIF (other than the BIF Notes). They can be used in any script command that takes a parameter, instead of specifying constant (hardcoded) data. BIF Variables start with an asterisk (*) and are then immediately followed by the BIF 'section' and 'tag' of the item. PRINT *[G]desc | | | Asterisk---- | | | | BIF Section--- | | BIF Tag---------- The command above tells Intellicomm to access the [G]eneral BIF section (General screen as in the BIF Editor) for the tag "desc" (short for description; the BBS/Host name), and print the value to the screen. You may also wish to use BIF Variables in WHEN commands: WHEN *[L]namp SEND *[L]namc This sends the BIF namc 'name command' (response) WHEN the BIF namp 'name prompt' is found. Both items are in the BIF [L]ogon section. You can do the same with ANY script command that takes a parameter, instead of specifying constant text. All the BIF sections and tags are listed in this appendix, along with any special conditions or considerations. NOTE: BIF Variables cannot change the BIF on-disk. BIFs are loaded from disk into MEMORY automatically by Intellicomm when you dial a BBS (via manual or automated means) or when you use the LOADBIF command in your script. If you change BIF Variables via ASSIGN or another script assignment command and wish to save the changes to disk you must use SAVEBIF to write the changes to disk. The $BIF_NAME System Variable holds the filename of the currently loaded BIF (without the .BIF extension). As with the System Variables, if you CHANGE any of the BIF items using ASSIGN or any other script assignment command, you change the data that Icom is working with as well, for the duration of the session or until another BIF is loaded. To avoid potential problems when running scripts from automated jobs, you can either save/restore original BIF data as we did above with the System Variables, or can simply use LOADBIF $BIF_NAME when your script ends, to reset all the BIF variables to their original values. Below, are all six BIF screens with the appropriate BIF Variable to use in a script displayed where the BIF data would normally be displayed: Intellicomm v2.01 SCRIPT.DOC 214 ╔═╡ BIF Editor Θ Editing VARIABLE.BIF ╞ General BBS Information ╞═══════╗ ║ BBS/Host Name > *[G]desc Message Type > *[G]mtyp ║ ║ Phone Number > *[G]phn1 Bank Type > *[G]btyp ║ ║ Phone Number > *[G]phn2 LD Service . . . *[G]ldsv ║ ║ Phone Number > *[G]phn3 City/Address . . *[G]city ║ ║ Phone Number > *[G]phn4 CR w/Commands? . *[G]adcr ║ ║ Phone Number > *[G]phn5 Add Line Feeds? *[G]adlf ║ ║ Port Settings > *[G]port Case-sensitive? *[G]case ║ ║ Dial Prefix . . *[G]dpre Connect Command *[G]conc ║ ║ Max. Redials . . *[G]datt Gen. Menu Exit . *[G]mcan ║ ╟─┤ Protocols ├───────────────────────┤ Miscellaneous/Timeouts ├────────╢ ║ Send Mail . . . *[G]mspr Last Connected . *[G]date ║ ║ BBS Letter . . *[G]msbl Total Connects . *[G]nses ║ ║ Receive Mail . . *[G]mrpr Response Delay . *[G]rdel ║ ║ BBS Letter . . *[G]mrbl BS Protection . *[G]bspt ║ ║ Send Files . . . *[G]fspr Logon Timeout . *[G]lout ║ ║ BBS Letter . . *[G]fsbl General Timeout *[G]gout ║ ║ Receive Files . *[G]frpr Max. Timeouts . *[G]tmax ║ ║ BBS Letter . . *[G]frbl Max. Online Time *[G]monl ║ ╚═══════════════════════════════════════════════════════════════════════╝ ╔═╡ Logon/Global Commands ╞═══════════╡ Logon/Global Prompts ╞══════════╗ ║ [Escape] Answer *[L]escc [Escape] Prompt *[L]escp ║ ║ Your Logon Name> *[L]namc Name . . . . . . *[L]namp ║ ║ Password Answer> $PASSWORD Password . . . . *[L]pasp ║ ║ Mode/Language > *[L]lanc Mode/Language . *[L]lanp ║ ║ Confirm Answer . *[L]ecnc Confirm . . . . *[L]ecnp ║ ║ Graphics Answer *[L]grac Graphics . . . . *[L]grap ║ ║ Scan Answer . . *[L]scac Scan Messages . *[L]scap ║ ║ Pause Answer . . *[L]pauc Pause . . . . . *[L]paup ║ ║ No More . . . . *[L]nomc More . . . . . . *[L]morp ║ ║ Birth Date . . . *[L]bdtc Enter Birth Date *[L]bdps ║ ║ Home Phone . . . *[L]phnc Enter Home Phone *[L]phnp ║ ║ Startup Command *[L]icom Main Menu A . . *[L]mnap ║ ║ Logoff . . . . . *[L]lofc Main Menu B . . *[L]mnbp ║ ║ Exit Command . . *[L]xitc Logged Off . . . *[L]lofp ║ ╚═══════════════════════════════════════════════════════════════════════╝ ╔═╡ Message Commands ╞════════════════╡ Message Prompts ╞═══════════════╗ ║ Access Msg Menu> *[M]ames Message Menu . . *[M]mmnp ║ ║ Send Replies . . *[M]senc Send Replies Now *[M]rulp ║ ║ Reply Filename > *[M]rnam Replies Accepted *[M]rokp ║ ║ Confirm Answer . *[M]crec Confirm Receive *[M]crep ║ ║ General Read . . *[M]grdc Receive Messages *[M]mdlp ║ ║ Personal Read . *[M]prdc Receive Success *[M]mokp ║ ║ Msg Filename > *[M]mnam More Mail Found *[M]mmfp ║ ║ Extract Newfiles *[M]mnew No Mail Found . *[M]mnop ║ ║ No Time Left . . *[M]mntp ║ ║ More Answer . . *[M]mmoc Message More . . *[M]mmop ║ ║ Leave Msg Menu . *[M]lmmc Message Pause . *[M]mpap ║ ║ Logoff Msg Menu *[M]gmmc Enter Protocol . *[M]mprp ║ ║ Reply Dir . . . *[M]repd ║ ║ Message Dir . . *[M]msgd ║ ╚═══════════════════════════════════════════════════════════════════════╝ Intellicomm v2.01 SCRIPT.DOC 215 ╔═╡ Bank Commands ╞═══════════════════╡ Bank Prompts ╞══════════════════╗ ║ Access Bnk Menu> *[B]abnk Bank Menu . . . *[B]bmnp ║ ║ Deposit Bytes . *[B]dbtc Deposit Bytes . *[B]dbtp ║ ║ Deposit Time . . *[B]dtmc Deposit Time . . *[B]dtmp ║ ║ Withdraw Bytes . *[B]wbtc Withdraw Bytes . *[B]wbtp ║ ║ Withdraw Time . *[B]wtmc Withdraw Time . *[B]wtmp ║ ║ Leave Bank Menu *[B]lbmc Bank Pause . . . *[B]bpap ║ ║ Logoff Bank Menu *[B]gbmc Bank More . . . *[B]bmop ║ ╟─┤ BBS File List Details ├───────────┤ BBS File List Details ├─────────╢ ║ Catalog to Use . *[B]catl Year Position . *[B]fysp ║ ║ D/L Priority > *[B]tdup Date separator . *[B]dase ║ ║ Default Lst Area *[B]dfar Comment Start . *[B]fcsp ║ ║ Filename Start . *[B]fnsp Comment End . . *[B]fcep ║ ║ Extension Start *[B]fesp Continue Comment *[B]fcca ║ ║ Size Position . *[B]fssp Continue Comment *[B]fccb ║ ║ Month Position . *[B]fmsp New File Area . *[B]fcat ║ ║ Day Position . . *[B]fdsp COUNT File Areas *[B]fnum ║ ╚═══════════════════════════════════════════════════════════════════════╝ ╔═╡ File Commands ╞═══════════════════╡ File Prompts ╞══════════════════╗ ║ Access File Menu *[F]afil File Menu . . . *[F]fmnp ║ ║ Default BBS Area *[F]fare File Pause . . . *[F]fpap ║ ║ Area Change . . *[F]facc File More . . . *[F]fmop ║ ║ New Files . . . *[F]nflc Enter D/L Fname *[F]efip ║ ║ File Search . . *[F]fsrc Enter U/L Fname *[F]efup ║ ║ Download File[s] *[F]fdlc Enter Protocol . *[F]fprp ║ ║ Upload File[s] . *[F]fulc Duplicate File . *[F]fdup ║ ║ Descrip @SCRIPT *[F]edsc Enter Descrip. . *[F]edsp ║ ║ Chars per Line . *[F]fcmx File Not Found . *[F]fnfp ║ ║ Max Lines . . . *[F]flmx No Time . . . . *[F]fitp ║ ║ Files per D/L . *[F]fpbt No Bytes . . . . *[F]fibp ║ ║ Files per U/L . *[F]fpul File Accepted . *[F]fokp ║ ║ Batch Full Answr *[F]fbfc Batch Full . . . *[F]fbfp ║ ║ File Password . *[F]fepc <Enter Password *[F]feep ║ ║ Leave File Menu *[F]lfmc Download File[s] *[F]fdlp ║ ║ Logoff File Menu *[F]gfmc Upload File[s] . *[F]fulp ║ ║ Upload PATH . . *[F]upld Transfer Abort . *[F]fabp ║ ║ Download Dir . . *[F]dnld Transfer Okay . *[F]fsup ║ ╚═══════════════════════════════════════════════════════════════════════╝ ╔═╡ Extra Commands ╞══════════════════╡ Extra Prompts ╞═════════════════╗ ║ External Extra A *[E]exac External A . . . *[E]exap ║ ║ External Extra B *[E]exbc External B . . . *[E]exbp ║ ║ External Extra C *[E]excc External C . . . *[E]excp ║ ║ External Extra D *[E]exdc External D . . . *[E]exdp ║ ║ Message Extra A *[E]mxac Message A . . . *[E]mxap ║ ║ Message Extra B *[E]mxbc Message B . . . *[E]mxbp ║ ║ Message Extra C *[E]mxcc Message C . . . *[E]mxcp ║ ║ Message Extra D *[E]mxdc Message D . . . *[E]mxdp ║ ║ File Extra A . . *[E]fxac File A . . . . . *[E]fxap ║ ║ File Extra B . . *[E]fxbc File B . . . . . *[E]fxbp ║ ║ File Extra C . . *[E]fxcc File C . . . . . *[E]fxcp ║ ║ File Extra D . . *[E]fxdc File D . . . . . *[E]fxdp ║ ╚═══════════════════════════════════════════════════════════════════════╝ Intellicomm v2.01 SCRIPT.DOC 216 C. MAIN SETUP VARIABLES (Advanced Users Only) The Icom Main Setup Variables are used in the same way as the BIF Variables outlined above. You must precede the variable's 'tag' name with an asterisk, and are free to use it as a parameter in any script command that takes a parameter. However, the Main Setup Variables do not require a [S]ection as the BIF Variables do. You simply specify an asterisk (*) followed by one of the main setup tags listed below. Example: ;*swpon (swap on) is the default 'swapping' setting which determines ; whether Icom will swap itself out of memory when calling external ; programs variable s ;define a variable called 's' if *swpon = 2 assign s "whether connected or not" if *swpon = 1 assign s "only if not connected" if *swpon = 0 assign s "NEVER" print "Icom will swap out of memory " s ;note 's' following the text This would print one of the strings below: Icom will swap out of memory whether connected or not Icom will swap out of memory only if not connected Icom will swap out of memory NEVER For all of the on/off, yes/no settings, 1 means YES or ON, and 0 means NO or OFF. To turn a setting ON, you'd ASSIGN 1 to it: ASSIGN *swpon 1 ;turn swapping on ASSIGN *swpon 0 ;turn swapping off Make sure you read the notes in the summaries of each variable below before you think about changing any of these variables in your scripts. In many cases you will not get the results you expect without knowing all the details. For example, *swpon can be overridden by the DOS command to execute by preceding the command with SW: (swap on) or NS: (swap off). So if you had defined your Mail Reader (*mread Main Setup Variable) as SW:DELUXE.EXE in the main setup, changing *swpon would have no effect: ASSIGN *swpon 0 ;turn swapping OFF DOS *mread ;same as DOS "SW:DELUXE.EXE" Icom would swap itself out regardless, due to the SW: preceding the command. In other cases, you may change a Main Setup Variable and find that it has no effect at all. In many cases, by changing a Main Setup Variable, all you've done is changed the DEFAULT setting. You may not have changed the variable Icom itself is working with. For example, the $MSG_DIR System Variable holds the current Message Directory. The directory in this variable is EITHER the Main Setup Variable (*msgdir) OR the BIF Variable (*[M]msgd) since you can override the Main Setup Variable with a setting in the BIF. To change the variable that Icom is Intellicomm v2.01 SCRIPT.DOC 217 working with, you would change neither *msgdir nor *[M]msgd ... you'd change the $MSG_DIR System Variable. Where this is the case, it will be pointed out in the summaries below, so be sure to see all the details before you set out working with these variables. NOTE: As with the BIF Variables, if you change a Main Setup Variable it does not change the .INI (INItialization) file on-disk. It only changes the setting in MEMORY. To save changes to disk you must use SAVEINI. The $INI_NAME System Variable holds the filename of the currently loaded .INI (without the .INI extension). If you CHANGE any of the Main Setup Variables, you change the data that Icom is working with for the duration of the session (or until another .INI is loaded). To avoid potential problems, you can either save/restore original INI data as we did above with the System Variables, or can simply use LOADINI $INI_NAME when your script ends, to re-load the original .INI and thus reset ALL the Main Setup Variables to their original values. Until you're experienced with the FORMAT of the Main Setup Variables it is recommended that you do NOT change any of the main setup information. To gain experience, use the normal Icom main setup menu to see what options go with a given item, then use the PRINT command (or simply view the ICOM.INI file in the File Viewer) to see how the options are represented. Many options use NUMBERS to represent various options (0 means one thing, 1 means another 2 means something else, etc., or 0 represents OFF while 1 represents ON for toggle items). Note that several main setup variables will have no effect if you change them, until a SAVEINI / LOADINI is performed. For example, if you change the *ssize (Screen Size) variable, the actual screen size will not change until a SAVEINI / LOADINI is performed. LOADINI actually does the work of resetting Intellicomm with new values, but if you change main setup variables and use LOADINI *without* using SAVEINI first, you'll lose any changes you made to the main setup variables. If you don't want to over- write the ICOM.INI file, do something like this: variable oldini $INI_NAME ;SAVE original main setup filename ASSIGN *somevariable "Some value" ... SAVEINI "$TEMP" ;save new values to a temporary INI file LOADINI "$TEMP" ;load the temporary INI file to reset Icom ... ;main body of script goes here LOADINI oldini ;reset with the usual values DELETE $HOME_DIR "$TEMP.INI" ;you can delete the file before your script ; exits, as long as you load another INI ; file first Intellicomm v2.01 SCRIPT.DOC 218 ╔═╡ User Settings ╞═════════════════════════════════════╗ ║ Alt-1 First Last Name : *uname ║ ║ Alt-2 BBS Password : $PASSWORD ║ ║ Alt-3 Street Address : *uaddr ║ ║ Alt-4 City, State/Prov: *ucity ║ ║ Alt-5 ZIP/Postal Code : *uzip ║ ║ Alt-6 Business Phone #: *ubphn ║ ║ Alt-7 Home Phone # : *uhphn ║ ║ Alt-8 Date of Birth : *udtob ║ ║ Alt-9 General Use : *alt9 ║ ║ Alt-0 General Use : *alt0 ║ ╚═══════════════════════════════════════════════════════╝ ╔═╡ General Settings ╞══════════════════════════════════╗ ║ Password Access Key . . . N/A ║ ║ Base and Startup Area . . *sarea ║ ║ TAB / Shift-TAB moves the *swptab ║ ║ Put Overlays in XMS/EMS . *overlay ║ ║ Enable Swapping . . . . . *swpon ║ ║ Release Time Slices? . . *rslice ║ ║ Drop RTS on Disk I/O? . . *droprts ║ ║ Mouse Settings . . . . . *mouse (see below) ║ ║ Use PATH to Locate Files *pathsch ║ ║ File Renumber Mode . . . *rmode ║ ║ Usage Log Renumber Total *usenum ║ ║ Capture Renumber Total . *capnum ║ ║ Message Renumber Total . *msgnum ║ ║ Reply Renumber Total . . *repnum ║ ║ Auto-Open Usage Log . . . *useopen ║ ║ Open Capture on Connect . *capopen ║ ║ Stamp Date/Time Cap Open *capstamp ║ ║ Sound . . . . . . . . . . *sound ║ ║ Pager . . . . . . . . . . *pager ║ ║ Date Format . . . . . . . *date ║ ║ Date Separator . . . . . *datesep ║ ║ Time Format . . . . . . . *time ║ ║ Time Separator . . . . . *timesep ║ ╚═══════════════════════════════════════════════════════╝ Mouse Mode : 0=Off 1=Righthanded 2=Lefthanded Mouse Speed: not adjustable from scripts. ╔═╡ Filenames and Paths ╞═══════════════════════════════╗ ║ Mail Reader> *mread ║ ║ Reply Dir > *repdir ║ ║ Message Dir> *msgdir ║ ║ Main Unpack> *unpak1 ║ ║ 2nd Unpack> *unpak2 ║ ║ Arc. Viewer> *zipview ║ ║ File Viewer *flister ║ ║ Extnl Editor *editor ║ ║ Alt-N Hotkey *hkey1c ║ ║ Description *hkey1t ║ ║ Alt-O Hotkey *hkey2c ║ Intellicomm v2.01 SCRIPT.DOC 219 ║ Description *hkey2t ║ ║ BIF Dir . . *lbif ║ ║ Catalog Dir *dbfpath ║ ║ Filelist Dir *lstdir ║ ║ Upload PATH *updir ║ ║ Download Dir *dldir ║ ║ Script Dir . *scrdir ║ ║ Usage Log . *usefile ║ ║ Capture File *capfile ║ ║ Screen Cap . *scap ║ ║ Swap Dir . . *swpdir ║ ║ Printer . . *prn ║ ╚═══════════════════════════════════════════════════════╝ ╔═╡ Screen/Color Settings ╞═════════════════════════════╗ ║ Menu Style/Colors . . . . (See below) ║ ║ Default Screen Size . . . *ssize ║ ║ Screen Write Mode . . . . *vmode ║ ║ Blank Screen # Seconds . *scrblank ║ ║ Status Window Delay . . . *sdelay ║ ╚═══════════════════════════════════════════════════════╝ ╔═╡ Screen/Color Settings ╞═════════════════════════════╗ ║ Menu Style *bstyle ║ ║ Border *border ║ ║ Selected/Hilit *bar ║ ║ Unselected/background *norm ║ ║ Bold/Hotkey *bold ║ ║ Terminal *tcolor ║ ║ Status Line *scolor ║ ╚═══════════════════════════════════════════════════════╝ ╔═╡ Debugging Log Settings ╞════════════════════════════╗ ║ Debugging Level . . . . . *dbglevel ║ ║ Debugging Log Filename. . *dbgfname ║ ║ Log Renumber Total . . . *dbgnum ║ ╚═══════════════════════════════════════════════════════╝ ╔═╡ Sysop Settings ╞════════════════════════════════════╗ ║ Export D/L's to TEXT FILE *xfile ║ ║ Export by ID/Conference? *xconf ║ ║ BIF Format for Export . . *xbif ║ ║ Move files to Subdir . . *msdir ║ ╚═══════════════════════════════════════════════════════╝ ╔═╡ Terminal Settings ╞═════════════════════════════════╗ ║ Default Comm. Port > *port ║ ║ Default Port Settings > *csettings ║ ║ Software Flow Control > *flowctrl (see below) ║ ║ Hardware Flow Control > *flowctrl (see below) ║ ║ Initialize Modem String > *minit ║ ║ Modem Hangup String > *mhang ║ ║ Confirm Hangup? . . . . . *hconfirm ║ ║ Drop DTR to Hangup? . . . *dtrhangup ║ Intellicomm v2.01 SCRIPT.DOC 220 ║ Init Modem at Startup? . *istart ║ ║ Init Modem if Connected? *cdinit ║ ║ Status Bar . . . . . . . *statbar ║ ║ Status Bar Displays . . . *statbarsp ║ ║ Scrollback Size [Kbytes] *sbsize ║ ║ Receive Buffer Size [K] . *rxbuf ║ ║ Transmit Buffer Size [K] *txbuf ║ ║ Echo . . . . . . . . . . *echo ║ ║ Add Line Feeds . . . . . *addlf ║ ║ Backspace Destructive? . *bsdest ║ ║ Send DEL as Backspace? . *bsswap ║ ║ Enable 16550 if Found? . *16550fl ║ ║ 16550 Receive Trigger . . *16550rx ║ ║ 16550 Transmit Trigger . *16550tx ║ ║ ENQ Response/@SCRIPT . . *enqstr ║ ╚═══════════════════════════════════════════════════════╝ *flowctrl: ADD the following values; 0 = No flow control 1 = XON/XOFF 2 = XON=any char/XOFF 4 = CTS/RTS 8 = DSR/DTR EXAMPLES: ASSIGN *flowctrl 1 ;XON/XOFF only ASSIGN *flowctrl 4 ;CTS/RTS only ASSIGN *flowctrl 5 ;XON/XOFF and CTS/RTS (1 + 4) You must use a 'PORT $COM_PORT' command (re-open the current COM port) for changes to *flowctrl to take effect. ╔═╡ Dialer Settings ╞═══════════════════════════════════╗ ║ Dial Prefix 1 > *dpre1 ║ ║ Dial Prefix 2 . . . . . . *dpre2 ║ ║ Dial Prefix 3 . . . . . . *dpre3 ║ ║ ! Dial Code . . . . . . . *dcode! ║ ║ @ Dial Code . . . . . . . *dcode@ ║ ║ $ Dial Code . . . . . . . *dcode$ ║ ║ Dial Suffix . . . . . . . *dsuff ║ ║ Dial Connected > *dconnect ║ ║ Minimum CONNECT Speed > *minspeed ║ ║ Auto Baud Adjustment > *baudetect ║ ║ Dial Busy/Retry 1 > *dagain1 ║ ║ Dial Busy/Retry 2 > *dagain2 ║ ║ Dial Busy/Retry 3 > *dagain3 ║ ║ Exclude Dialing 1 > *dabort1 ║ ║ Exclude Dialing 2 > *dabort2 ║ ║ Exclude Dialing 3 > *dabort3 ║ ║ Dial Timeout . . . . . . *dtime ║ ║ Stop Dialing . . . . . . *dstop ║ ║ Pause Between Dials . . . *dpause ║ ║ Attempts per BIF/Cycle . *dcycle ║ ║ LD Service Phone Num . . *ldnum ║ ╚═══════════════════════════════════════════════════════╝ Intellicomm v2.01 SCRIPT.DOC 221 ╔═╡ File Transfer Settings ╞════════════════════════════╗ ║ POSTFILE.SCR Settings (See below) ║ ║ Move Old Downloads? > *dlmove ║ ║ Cancel D/L No Time/Bytes *candl ║ ║ Auto Zmodem Receive . . . *zauto ║ ║ Auto Zmodem Protocol . . *zprotocol ║ ║ Zmodem Crash Recovery . . *zrresume ║ ║ Filename Conversion . . . *fconv ║ ║ Manage Duplicate Files . *fmanage ║ ║ Delete Aborted Transfers *delabort ║ ║ Disk Buffer Size [Kbytes] *xdbufsiz ║ ║ ASCII Transfers . . . . . (See table below) ║ ╚═══════════════════════════════════════════════════════╝ POSTFILE.SCR Settings: Settings for POSTFILE.SCR are stored in $SCRIPT_DIR\POSTFILE.INI. This is a straight ASCII text file that stores one setting per line, and the file can be read and/or modified with a script if necessary. See POSTINI.SCR for details; look for FOPEN, FGETS and FPUTS commands. These read and write to POSTINI.SCR just as you can do in your own scripts. Do not add any new settings to POSTFILE.INI, however, nor change the order in which the items are stored. ASCII Transfers: ╔═╡ ASCII Transfer Details ╞════════════════════════════╗ ║ Line Pacing/Delay [tenths] *alpace ║ ║ Char Pacing/Delay [tenths] *acpace ║ ║ Receive Timeout [seconds] *atmout ║ ╚═══════════════════════════════════════════════════════╝ ╔═╡ External Protocols ╞════════════════════════════════╗ ║ ║ ║ Descrip Hotkey Receive Send Cmd. Ask? ║ ║ ║ ║ 1. *prot1n *prot1k *prot1r *prot1s *prot1f ║ ║ 2. *prot2n *prot2k *prot2r *prot2s *prot2f ║ ║ 3. *prot3n *prot3k *prot3r *prot3s *prot3f ║ ║ etc... up to 8 ║ ╚═══════════════════════════════════════════════════════╝ ╔═╡ Host Mode Settings ╞════════════════════════════════╗ ║ Sysop Name . . . . . . . *hsysop ║ ║ Host Download Dir . . . . *hdldir ║ ║ Host Upload Dir . . . . . *huldir ║ ║ Level 1 Password . . . . (See below) ║ ║ Level 2 Password . . . . (See below) ║ ║ DOS Shell Password . . . (See below) ║ ║ Abort Host Password . . . (See below) ║ ║ Modem Init Host Command . *hminit ║ ║ Modem Offhook Command . . *hoffhook ║ ║ Modem Answer Command . . *manswer ║ ║ Modem OK Message . . . . *mokay ║ ║ Modem RING Message . . . *mring ║ ║ Answer on Ring # . . . . *hrings ║ ║ Main Setup File for Host *hini ║ Intellicomm v2.01 SCRIPT.DOC 222 ║ Level 1 can OVERWRITE? . *hoverwrite (0=No; 1=Yes ║ ║ Level 1 EXTNL Protocols? *hextp (0=No; 1=Yes) ║ ║ Direct CABLE Link? . . . *hcable (0=Modem; 1=Cable) ║ ╚═══════════════════════════════════════════════════════╝ The host passwords are stored separately in the file $HOME_DIR\HOST.PWD. This is a straight ASCII text file and each password is stored on a separate line. To read the passwords: variable pass1 variable pass2 variable dospass variable abortpass variable f $HOME_DIR "HOST.PWD" fopen f f "r" ;open in read mode fgets pass1 f ;Level 1 Password fgets pass2 f ;Level 2 Password fgets dospass f ;DOS Shell Password fgets abortpass f ;Abort Host Password fclose f ;close HOST.PWD To write new passwords to disk, replace "r" (read) in the FOPEN command with "w" (write), and replace the four FGETS commands with FPUTS. Note that FPUTS reverses the order of the variable and the file handle: fputs f pass1 ;file handle first ╔═╡ Comm Port Settings ╞════════════════════════════════╗ ║ COM1 Base Address . . . . *com1b ║ ║ IRQ Line . . . . . . *com1i ║ ║ COM2 Base Address . . . . *com2b ║ ║ IRQ Line . . . . . . *com2i ║ ║ COM3 Base Address . . . . *com3b ║ ║ IRQ Line . . . . . . *com3i ║ ║ etc... up to 8 ║ ╚═══════════════════════════════════════════════════════╝ You must use a 'PORT' command (re-open the current COM port) for changes to *com?b / *com?i to take effect. ╔═╡ File Tagger Settings ╞══════════════════════════════╗ ║ File Transfer Speed [CPS] *acps ║ ║ Tagger Screen Size . . . *tssize ║ ║ Description Lines Shown . *split ║ ║ Auto Hilight Bar Lock . . *ahlock ║ ║ View Date Filters Noted? *fnote ║ ║ Duplicate Checking . . . *ckdupe ║ ║ Use DOWNLOAD.NDX . . . . *dndx ║ ║ File .EXTensions in DNDX *dndxext ║ ║ DOWNLOAD.NDX Directories Stored in file DNDX.DIR ║ ║ Filter Graphics Chars . . *fgraph ║ ║ Replace Shorter Comments *ckcmts ║ ║ Extract NEWFILES / mail . *qwknew ║ Intellicomm v2.01 SCRIPT.DOC 223 ║ Auto Import New Files . . *taguse ║ ║ Keep an Upload Catalog . *tagimpt ║ ║ Purge Noted # Days Old . *prgnote ║ ║ Purge Untagged # Days Old *purge ║ ║ Auto Pack when # Purged . *ppack ║ ║ Auto Bookmark Update . . *abook ║ ║ Auto View Date Update . . *afdate ║ ╚═══════════════════════════════════════════════════════╝ ╔═╡ Tagger Keywords ╞═══════════════════════════════════╗ ║ Strip Comment Keywords . Stored in file STRIP.KWD ║ ║ Replace Word(s) Keywords Stored in file REPLACE.KWD ║ ║ Exclude File Keywords . . Stored in file EXCLUDE.KWD ║ ║ Note File Keywords . . . Stored in file NOTE.KWD ║ ║ Auto Tag Remaining Files? *atag ║ ╚═══════════════════════════════════════════════════════╝ Intellicomm v2.01 SCRIPT.DOC 224 D. COLOR CODES Using the codes below, you can create your own colors for use with the SCROLL (scroll or clear an area of the screen) and PRINTRAW commands (print directly to the screen in a specific color). You can also assign custom colors to the color variables Icom uses: $NORM_COLOR, $BOLD_COLOR, $BORDER_COLOR, etc., to draw menus (BARMENU, etc) and boxes (BOX). If your script is going to be used by others (if you intend to upload it to a BBS later, etc.) it is recommended that you do NOT use custom colors in your script at all. Laptop and monochrome displays cannot display all colors properly, so even if your script looks pretty on your screen, it is possible that it will be unreadable on someone else's screen. By using $BAR_COLOR, $BORDER_COLOR, $NORM_COLOR, $TERM_COLOR, $STAT_COLOR (see the System Variables appendix above for details) you can use the colors that the USER has set up in Intellicomm. This will give your script an integrated look with Intellicomm, and whenever the user changes colors in the Icom main setup, your script will also make use of the new colors! To create a custom color first pick your background color from the table below (the number of the color). Background colors can be ONLY the colors listed in the first column of the table (0-7). If you try to use a background color above 7, the foreground color will BLINK. Once you have your background color, multiply it by 16, then add the foreground color. Any of the 16 colors (0-15) may be used for a foreground color. The formula to create a color (and the background color limitation of using only 0-7) has nothing to do with the script language; it's simply how IBM video adaptors work. The formula is (with 'x' representing multiplication): COLOR = background x 16 + foreground 0 Black 8 Dark Gray 1 Blue 9 Light Blue 2 Green 10 Light Green 3 Cyan 11 Light Cyan 4 Red 12 Light Red 5 Magenta 13 Light Magenta 6 Brown 14 Yellow 7 Light Gray 15 White +128 Blink For example, to display white foreground text on a red background you'd multiply 4 (Red) by 16, then add 15 (White). The number you come up with (79) could then be used in PRINTRAW and SCROLL commands, or could be ASSIGNed to the various COLOR System Variables to change the colors Icom uses with the BOX, BOXGETS, MENUBAR, etc. commands. With PRINTRAW the color is the 3rd parameter: PRINTRAW $SCRN_X $SCRN_Y 79 "White text on a red background" Intellicomm v2.01 SCRIPT.DOC 225 To make the foreground text blink on and off, just add 128 to the original color value (79 + 128 = 207): PRINTRAW 1 1 207 "White blinking text on a red background" D.1 Using Color Variables If you intend to use custom colors in your script, you still might want to use variables to specify colors, instead of specifying color values in individual SCROLL/PRINTRAW/CLS, etc. commands. Example: VARIABLE color1 7 ;gray on black VARIABLE color2 23 ;light gray on blue ;now, use these color variables in the rest of the script PRINTRAW 1 1 color1 "Some text" CLS color2 ...etc. Then, if you want to change the colors later all you'll have to do is change the color assigned to the variables (make one change), instead of having to change each individual color code in the commands themselves. Alternatively, you can simply ASSIGN new color codes to the usual Icom color variables, then use BOXGETS, the MENUXXXX commands, WNDOPEN, PRINT, etc (which all use the regular $XXXX_COLOR variables). Just make sure to save the old color values and restore them when your script exits: VARIABLE old_norm_color $NORM_COLOR ;save existing color values VARIABLE old_border_color $BORDER_COLOR ASSIGN $NORM_COLOR 112 ;black on light gray (semi-paper white) ASSIGN $BORDER_COLOR 31 ;white on blue WNDOPEN "Window Border is White on Blue" PRINT "Text in window is Black on White" ASSIGN $NORM_COLOR old_norm_color ;restore original values ASSIGN $BORDER_COLOR old_border_color E. ASCII CODES ASCII stands for "American Standard Code for Information Interchange", and the ASCII character set is what lets our computers display things on- screen and print things such as this document. Computers understand one thing, and one thing only: numbers. They don't understand the letters numbers or symbols we humans use, so someone had to assign numbers to all the characters and symbols, so that computers could display and print characters that we humans use. The ASCII codes listed below are the numeric equivalent of characters/symbols that most all personal computers use. Intellicomm v2.01 SCRIPT.DOC 226 E.1 How to Use the ASCII Table The numbers listed in the 'Num' column below are the ASCII codes for all the characters, and are for use only with the SENDKEY command. SENDKEY 32 is equivalent to SENDNC " " (send a space; SENDNC doesn't add a CR as SEND does). SENDKEY 8 sends a backspace (BS) to the BBS, SENDKEY 65 sends the letter "A" (see the extended keycodes in the next section for more). The characters listed in the 'Char' column are the character equivalents, which can be used in any script 'string' (between quotes). To send a Ctrl-C to the BBS you'd use SENDNC "^C". To send two ESC character you'd use SENDNC "^[^[", etc. The "Name" column (control characters) is for reference only. You cannot use SEND ESC to send an ESC character. Num Char Name Num Char Num Char Num Char ------------- -------- -------- -------- 0 ^@ NUL 32 64 @ 96 ` 1 ^A SOH 33 ! 65 A 97 a 2 ^B STX 34 " 66 B 98 b 3 ^C ETX 35 # 67 C 99 c 4 ^D EOT 36 $ 68 D 100 d 5 ^E ENQ 37 % 69 E 101 e 6 ^F ACK 38 & 70 F 102 f 7 ^G BEL 39 ' 71 G 103 g 8 ^H BS 40 ( 72 H 104 h 9 ^I HT 41 ) 73 I 105 i 10 ^J LF 42 * 74 J 106 j 11 ^K VT 43 + 75 K 107 k 12 ^L FF 44 , 76 L 108 l 13 ^M CR 45 - 77 M 109 m 14 ^N SO 46 . 78 N 110 n 15 ^O SI 47 / 79 O 111 o 16 ^P DLE 48 0 80 P 112 p 17 ^Q DC1 49 1 81 Q 113 q 18 ^R DC2 50 2 82 R 114 r 19 ^S DC3 51 3 83 S 115 s 20 ^T DC4 52 4 84 T 116 t 21 ^U NAK 53 5 85 U 117 u 22 ^V SYN 54 6 86 V 118 v 23 ^W ETB 55 7 87 W 119 w 24 ^X CAN 56 8 88 X 120 x 25 ^Y EM 57 9 89 Y 121 y 26 ^Z SUB 58 : 90 Z 122 z 27 ^[ ESC 59 ; 91 [ 123 { 28 ^\ FS 60 < 92 \ 124 | 29 ^] GS 61 = 93 ] 125 } 30 ^^ RS 62 > 94 ^ 126 ~ 31 ^_ US 63 ? 95 _ 127 DEL IBM enhanced the standard ASCII set and added the characters in the next table below. To enter these characters in a "string" in a script, hold down your [Alt] key, then enter the number in the 'Num' column on the NUMERIC KEYPAD, and release the [Alt] key (don't use the numbers at the Intellicomm v2.01 SCRIPT.DOC 227 top of the keyboard... they don't work). For example, to enter this command in a script: print "Ç" type 'print"', and while holding down the [Alt] key, press [1], [2], [8] (character 128 is Ç) on the NUMERIC KEYPAD, release the [Alt] key (the Ç will then then be inserted), then enter the trailing quote ("). To send extended characters out the COM port, either use the same technique above with SEND or SENCNC, or use the number of the character (the 'Num' column below) with SENDKEY. E.g., SENDKEY 128 sends Ç. This table may not be printed properly if your printer can't handle extended ASCII characters: Num Char Num Char Num Char Num Char -------- -------- -------- -------- 128 Ç 144 É 192 └ 208 ╨ 129 ü 145 æ 193 ┴ 209 ╤ 130 é 146 Æ 194 ┬ 210 ╥ 131 â 147 ô 195 ├ 211 ╙ 132 ä 148 ö 196 ─ 212 ╘ 133 à 149 ò 197 ┼ 213 ╒ 134 å 150 û 198 ╞ 214 ╓ 135 ç 151 ù 199 ╟ 215 ╫ 136 ê 152 ÿ 200 ╚ 216 ╪ 137 ë 153 Ö 201 ╔ 217 ┘ 138 è 154 Ü 202 ╩ 218 ┌ 139 ï 155 ¢ 203 ╦ 219 █ 140 î 156 £ 204 ╠ 220 ▄ 141 Ä 157 ¥ 205 ═ 221 ▌ 142 Ä 158 ₧ 206 ╬ 222 ▐ 143 Å 159 ƒ 207 ╧ 223 ▀ 160 á 176 ░ 224 α 240 ≡ 161 í 177 ▒ 225 ß 241 ± 162 ó 178 ▓ 226 Γ 242 ≥ 163 ú 179 │ 227 π 243 ≤ 164 ñ 180 ┤ 228 Σ 244 ⌠ 165 Ñ 181 ╡ 229 σ 245 ⌡ 166 ª 182 ╢ 230 µ 246 ÷ 167 º 183 ╖ 231 τ 247 ≈ 168 ¿ 184 ╕ 232 Φ 248 Φ 169 ⌐ 185 ╣ 233 Θ 249 Θ 170 ¬ 186 ║ 234 Ω 250 Ω 171 ½ 187 ╗ 235 δ 251 √ 172 ¼ 188 ╝ 236 ∞ 252 173 ¡ 189 ╜ 237 φ 253 ² 174 « 190 ╛ 238 ε 254 ■ 175 » 191 ┐ 239 ∩ 255 Intellicomm v2.01 SCRIPT.DOC 228 F. KEYBOARD CODES As with the characters computers display on the screen (see ASCII codes above), computers are unable to understand what an [A] or [B] is, since computers understand numbers and only numbers. So again, someone had to assign numbers to all the keys on the keyboard, and the various combinations of key presses such as [Alt-A], [Shift-F1] so that the computer could understand various key presses, and separate one key from another. Intellicomm's script processor does recognize text for the standard keys (you needn't deal with numbers to check for an [A] key press for example), but text equivalents are not available for most of the extended keys such as [Alt-A], [F1], etc. The tables below list the text equivalents of various key presses (where available) or the NUMBER of the key press where a text equivalent is not available. You'll need these keyboard codes for semi-advanced script projects where you need direct control over the keyboard. F.1 How to use the Keyboard Codes The tables below list all keys on a standard IBM XT or enhanced (101 key) AT keyboard. Note that the [F11] and [F12] function keys are only available on AT keyboards, so avoid using these two keys if you'll be distributing your script to the general public. The 'Key' column lists the actual key, the 'Norm' column lists the code of the key when pressed alone (without [Shift], [Ctrl] or [Alt]), the 'Shift' column lists the code of the key when pressed in combination with either the left or right [Shift] key, the 'Ctrl' column lists the code of the key when pressed in combination with either the left or right [Ctrl] key, and the 'Alt' column lists the code of the key when pressed in combination with either the left or right [Alt] key. The most common use of these tables is for use with the INKEY, INKEYW INKEYT and SENDKEY commands, or with the $HOTKEY_? variables. The numbers and/or characters in the tables below show you how to check or specify a given key press. Examples follow. Regular key presses (with a value below 255... keys in the standard ASCII code set) are always specified as a regular character between double quotes ("A", "B", "C", etc). Common control characters such as [Ctrl-A], [Ctrl-B], [Ctrl-C] are specified as a regular character preceded by a caret (^), between double quotes ("^A", "^B", "^C"). Extended key presses are always specified as a number WITHOUT double quotes ([Alt-A] for example is key code 7680). Note that if $KEY_CHECK is non-zero (non-zero means $KEY_CHECK is ON), Intellicomm's script processor and Icom's Terminal will 'eat' many extended key codes. For example, [Alt-A] is the standard Icom key to enter the Text Editor; in order to use [Alt-A] in your script you should set the $KEY_CHECK variable to zero before using INKEY / INKEYW / INKEYT: variable code variable old_kcheck $KEY_CHECK ;save original value assign $KEY_CHECK 0 ;set to 0 to check for extended key Intellicomm v2.01 SCRIPT.DOC 229 ; codes printnc "Press a key: " inkeyw code ;stores the key code in variable ; 'code' print "^M^JKey code is: " code assign $KEY_CHECK old_kcheck ;reset to original value NOTE: Various references to "extended key codes" are made in this document. "Extended" key codes are NUMERIC key codes below that are not specified in double quotes. A regular press of the [A] key, or [Shift- A], or [Ctrl-A] are NOT extended key codes (you can see this by looking at the table below, noticing that all of these [A] key codes are between double quotes; "a", "A", "^A"). Of the various [Al key combinations, only [Alt-A] is an 'extended' key code (extended key code # 7680). For commands or variables which specify that you MUST use an extended key code (the $HOTKEY_? variables for example), you cannot use any of the codes listed in double quotes below. This is not permitted: assign $HOTKEY_1 "A" ;[A] is not an extended key code This is fine: assign $HOTKEY_1 7680 ;[Alt-A] is an extended key code F.2 Example of Usage You must use the same format as listed in the tables below to test for various key strokes. The following example tests for all possible combination of the [A] key: variable code assign $KEY_CHECK 0 ;Necessary when checking for EXTENDED key codes ; which Icom uses for some function. Most ; extended key codes ARE used by Intellicomm for ; various functions. Below we're checking for ; [Alt-A], and since Icom uses [Alt-A] for "Text ; Editor" we have to TELL Intellicomm not to ; process any extended keys, or Icom will simply ; enter the Text Editor if the user presses [Alt- ; -A] printnc "Press [a], [Shift-a], [Ctrl-a], or [Alt-a]: " inkeyw code assign $KEY_CHECK 1 ;allow Icom to process extended key codes again if code = "a" print "[a] was pressed" if code = "A" print "[Shift-a] was pressed" if code = "^A" print "[Ctrl-a] or [Ctrl-A] was pressed" if code = 7680 print "[Alt-a] or [Alt-A] was pressed" Note that for [Ctrl] and [Alt] key combinations, [Alt-A] is the same as [Alt-a], and [Ctrl-A] is the same as [Ctrl-a] (case is not significant). Intellicomm v2.01 SCRIPT.DOC 230 UPPERCASE/lowercase applies only to the 'Norm' and 'Shift' columns. If the [Caps Lock] is enabled, 'Norm' and 'Shift' will be reversed (i.e. a normal [a] keypress is "A" and a [Shift-a] keypress is "a"). In most cases, if you want to check for an [A] keypress, you'll check for both "a" and "A" so that the user can ignore the state of the [Caps Lock] key: variable key inkeyw key switch key case "A" case "a" ... ;do something for either case, UPPER or lower endcase case "B" case "b" ... endcase ...etc endswitch The state of the [Num Lock] key also affects the keys on the numeric keypad, as discussed below. NOTE: Where "N/A" (not applicable) is listed below, it means that the keyboard hardware is not capable of returning a key code for a given state. For example, [Ctrl-1] doesn't return any key code at all, and such a key press will not even been seen by INKEY, INKEYW, INKEYT. N/A keys are a limitation of PC keyboard hardware and not of Intellicomm's script language.... just as the numbers returned by various keys are simply what PC hardware uses and are not assigned by the script language (the same numbers will work in a real program, or in any other script language that uses the regular keyboard scan codes). Key Norm Shift Ctrl Alt --------------------------------------------------------------- A "a" "A" "^A" 7680 B "b" "B" "^B" 12288 C "c" "C" "^C" 11776 D "d" "D" "^D" 8192 E "e" "E" "^E" 4608 F "f" "F" "^F" 8448 G "g" "G" "^G" 8704 H "h" "H" "^H" 8960 I "i" "I" "^I" 5888 J "j" "J" "^J" 9216 K "k" "K" "^K" 9472 L "l" "L" "^L" 9728 M "m" "M" "^M" 12800 N "n" "N" "^N" 12544 O "o" "O" "^O" 6144 P "p" "P" "^P" 6400 Q "q" "Q" "^Q" 4096 R "r" "R" "^R" 4864 Intellicomm v2.01 SCRIPT.DOC 231 S "s" "S" "^S" 7936 T "t" "T" "^T" 5120 U "u" "U" "^U" 5632 V "v" "V" "^V" 12032 W "w" "W" "^W" 4352 X "x" "X" "^X" 11520 Y "y" "Y" "^Y" 5376 Z "z" "Z" "^Z" 11264 1 "1" "1" N/A 30720 2 "2" "2" 768 30976 3 "3" "3" N/A 31232 4 "4" "4" N/A 31488 5 "5" "5" N/A 31744 6 "6" "6" N/A 32000 7 "7" "7" N/A 32256 8 "8" "8" N/A 32512 9 "9" "9" N/A 32768 0 "0" "0" N/A 33024 , "," "," N/A 13056 . "." "." N/A 13312 / "/" "/" N/A 13568 ; ";" ";" N/A 9984 ' "'" "'" N/A 10240 [ "[" "[" "^[" 6656 ] "]" "]" "^]" 6912 ` "`" "`" N/A 10496 - "-" "-" "^-" 33280 = "=" "=" N/A 33536 \ "\" "\" "^\" 11008 Key Norm Shift Ctrl Alt --------------------------------------------------------------- F1 15104 21504 24064 26624 F2 15360 21760 24320 26880 F3 15616 22016 24576 27136 F4 15872 22272 24832 27392 F5 16128 22528 25088 27648 F6 16384 22784 25344 27904 F7 16640 23040 25600 28160 F8 16896 23296 25856 28416 F9 17152 23552 26112 28672 F10 17408 23808 26368 28928 F11 34048 34560 35072 35584 F12 34304 34816 35328 35840 Enter "^M" "^M" "^J" 7168 Ins 20992 20992 37376 41472 Del 21248 21284 37632 41728 Esc "^[" "^[" "^[" 256 NOTE: The values in the table below assume that [Num Lock] is OFF. If [Num Lock] is ON, and the numeric keypad [Home], [End], etc., keys are used, the 'Norm' and 'Shift' fields will be REVERSED. I.e. if [Num Lock] is ON, [Home] will be key code "7" and [Shift-Home] will be key code 18176. Intellicomm v2.01 SCRIPT.DOC 232 The extended cursor control keys on AT-type keyboards (the cursor keys that are separated from the numeric keypad) return the same value for both 'Norm' and 'Shift', regardless of the state of [Num Lock]. I.e. whether [Num Lock] is on OR off, the extended [Home] key will always return 18176, and [Shift-Home] will also return 18176. Extended or "enhanced" (101 key) keyboard hardware DOES make a distinction between the extended cursor control key codes, and the numeric keypad cursor control key codes. Intellicomm's keystroke handler simulates the same key code for either though (either the extended [Home] key or the numeric keypad [Home] key for example), to simplify keyboard handling. Key Norm Shift Ctrl Alt --------------------------------------------------------------- Home 18176 "7" 30464 38656 End 20224 "1" 29952 40704 PgUp 18688 "9" 33792 39168 PgDn 20736 "3" 30208 41216 Up 18432 "8" 36096 38912 Down 20480 "2" 37120 40960 Left 19200 "4" 29440 39680 Right 19712 "6" 29696 40192 Tab "^I" 3840 37888 42240 BckSpc "^H" "^H" " " 3584 Kpad 5 19456 "5" 36608 N/A Grey * "*" "*" 38400 N/A Grey - "-" "-" 36352 18944 Grey + "+" "+" 36864 19968 Intellicomm v2.01 SCRIPT.DOC 233 G. SCRIPT ERROR MESSAGES/SOLUTIONS Error : "OPERATOR is an invalid operator; =, <>, <, <=, >, >= only" Reason: An invalid operator was specified in an IF or WHILE command. Valid operators are =, <>, <, <=, >, >=. See IF in the Detailed Command Summary for details. Error : "Parameter missing in IF/WHILE" Reason: An operator was specified (<, <=, =, >= >) but no parameter followed to carry out the comparison. Add an argument after your operator. E.g. 'IF X = ' is illegal, 'IF X = 1' is fine. Error : "No ']' in BIF Variable" Reason: *[ (the BIF variable *[X]tag prefix) was specified but no closing ']' was found. Ensure that you have a closing bracket in the variable and that there are no spaces ('*[ X ]tag' is illegal; use '*[X]tag'). Error : "Bad section [X] in BIF Variable" Reason: The section (*[X]tag) specified in a BIF Variable was unknown. See BIF Variable Appendix for details. Error : "Bad tag [sTAG] in BIF Variable" Reason: The sTAG (*[X]sTAG) specified in a BIF Variable was unknown. See BIF Variable Appendix for details. Error : "Bad tag [sTAG] in INI Variable" Reason: A bad main setup tag followed the asterisk in a variable specification (*tag). See the Main Setup Variables appendix for valid tags. Error : "No command with WHEN" Reason: A prompt string was specified with WHEN, but no command was specified (the command to execute when the prompt is found). Add a command after the prompt. Error : "cCOMMAND command/label not found" Reason: cCOMMAND is not a recognized command or label. Check the command/label carefully for typing errors. Error : "LABELNAME label not found." Reason: The label following GOTO or GOSUB was not found in the script. Check the label carefully for typing errors. Error : "cCOMMAND requires a VARIABLE as the first parameter" Reason: The first paremter following cCOMMAND was not a variable. Script commands that assign or change data require a variable as their first parameter. Either define a variable using the VARIABLE command, and specify the variable's name as the first parameter following cCOMMAND, or use a GlobalStr[] or read/write System Variable as the first parameter. Error : "cCOMMAND called before MENUDEFINE" Reason: MENUBAR, MENUBOXH, or MENUBOXV was executed before MENUDEFINE was Intellicomm v2.01 SCRIPT.DOC 234 used. See MENUDEFINE in the Detailed Command Summary for details. Error : Menu item [nITEM] is invalid [no such item] Reason: An invalid menu item number was specified in a MENUHLP command. See MENUHLP in the Detailed Command Summary for details. Error : "Bad GOTO/GOSUB; No label/variable name" Reason: GOTO or GOSUB was used, but no label name followed. Specify a label to jump to after the GOTO or GOSUB command. Error : "Bad GOTO/GOSUB; Bad 1st character in label/variable name" Reason: The first character in the label name following the GOTO or GOSUB command is invalid. The first character in a label name must be in the range a-z, A-Z or an underscore (_). Numbers are not valid first characters in label names. Error : "Bad GOTO/GOSUB; Bad character [X] in label/variable name" Reason: An invalid character was used in a label name. You may only use alphanumeric characters (a-z, A-Z, 0-9) and underscores (_) in script labels. Error : "Can't define vVARIABLE; No label/variable name" Reason: No variable label name was specified after the VARIABLE command. You must specify a legal variable name after the VARIABLE command (see 'Bad 1st character' and 'Bad character' just below for information on valid variable names). Error : "Can't define vVARIABLE; Bad 1st character in label/variable name" Reason: The first character in the variable name following the VARIABLE command is invalid. The first character in a variable name must be in the range a-z, A-Z or an underscore (_). Numbers are not valid first characters in variable names. Error : "Can't define vVARIABLE; Bad character [c] in label/variable name" Reason: An invalid character was used in a variable name. You may only use alphanumeric characters (a-z, A-Z, 0-9) and underscores (_) in script variable names. Error : "Can't define vVARIABLE; Max variables reached" Reason: The variable table is full. No more than 35530 variables may be defined in any one script. See the SCRIPT MEMORY LIMITS appendix below for possible solutions. If you split your script up into two or more scripts, you can define more than 35530 variables total. Error : "Can't define vVARIABLE; No memory" Reason: The computer is out of memory and there was none left to allocate the variable. Reduce the number of variables in your script by using global 'working' variables which you use throughout the script. For example, if you need to count from 1 to 10 in ten different places in your script, use the same variable to do the Intellicomm v2.01 SCRIPT.DOC 235 counting instead of defining separate variables each time. Error : "Can't define vVARIABLE; Variable exists" Reason: The variable name following the VARIABLE command has already been defined elsewhere in the script. Use a different variable name. Error : "Can't define vVARIABLE; Name duplicates a script COMMAND" Reason: To allow for future script enhancements, variable names cannot duplicate script commands. For example, 'VARIABLE variable' is illegal since the variable name ('variable') duplicates the VARIABLE command. Use another variable name. Error : "Can't assign data to vVARIABLE; no memory" Reason: The computer is out of memory and there was none left to allocate data to a defined variable. Memory for variables is allocated based on the length of the data assigned to a variable, and the total number of variables. Reduce the number of variables in your script by using global 'working' variables which you use throughout the script. For example, if you need to count from 1 to 10 in ten different places in your script, use the same variable to do the counting instead of defining separate variables each time. Error : "Undefined variable; vVARIABLE" Reason: A variable name was specified, but it does not exist. Check the variable name carefully to ensure that you have defined it with the VARIABLE command (or see the BIF Variables / Main Setup Variables appendices if applicable). Error : "vVARIABLE variable is read only" Reason: You attempted to assign data to a read only $SYSTEM variable. Error : "GlobalStr missing ]" Reason: 'GlobalStr[' was specified but no closing ']' was found. Ensure that you have a closing bracket in the variable and that there are no spaces ('GlobalStr[ X ]' is illegal; use 'GlobalStr[X]'). Error : "GlobalStr[nOFFSET] is out of bounds [0-9 only]" Reason: The offset specified between the GlobalStr brackets is invalid. Valid offsets are numbers from 0-9 only. Error : "Invalid variable in GlobalStr; vVARIABLE" Reason: A variable name was specified as the GlobalStr offset (e.g. GlobalStr[variable_name]) but variable_name is invalid. Only user-defined variables are valid as GlobalStr offsets. Define the variable with the VARIABLE command before using it in GlobalStr. Error : "Not enough memory ... Can't perform function." Reason: All of the computer's memory has been used up. This is a general purpose error message that can occur with many script commands, and the only solution is to reduce the size of your script (see the SCRIPT MEMORY LIMITS appendix below), or to increase the amount of memory on your computer (use MEMMAKER, QEMM, etc). Intellicomm v2.01 SCRIPT.DOC 236 Note that memory above 640K is not useable by DOS programs or scripts, so the only way to make 'more' memory available is to move device drivers and TSR's out of conventional memory, and into upper memory. Error : "Division by zero" Reason: One of the parameters in the DIV(ide) command is zero. Division by zero is invalid and you must change the offending parameter to a non-zero value. Error : "GOSUB stack overflow [16 GOSUB maximum]" Reason: GOSUB was executed more than 16 times before a RETURN was found. When GOSUB's are executed, the script address (line number) to jump to when a RETURN is found is stored in an internal script 'stack'. This stack is only capable of holding 16 RETURN addresses. You must simplify your script logic to solve the problem. Error : "FOPEN stack overflow [16 FOPEN maximum]" Reason: You attempted to FOPEN more than 16 files at a time. Call FCLOSE to close one or more files before the offending FOPEN. Error : "FOPEN mode "%s" is invalid [r, w, a, r+, w+, a+ only]" Reason: The mode specified in the FOPEN command (3rd parameter) was invalid. See FOPEN in the Detailed Command Summary for details. Error : "nHANDLE is an invalid file number" Reason: The file handle specified in a file-related command (FGETS, FPUTS, FCLOSE, etc) is invalid. You must obtain a valid file handle with the FOPEN command before using file-related commands. A given file handle is also invalid after FCLOSE is used on the file. Error : "cCOMMAND stack overflow." Reason: VPUSH was used more than 16 times before VPOP, WNDOPEN was used more than 16 times before WNDCLOSE, or WAITFOR was nested (likely via a 'WHEN "text" gosub subroutine' command where WAITFORs are used in the subroutine) more than 16 times. Error : "BREAK|CONTINUE|ENDWHILE without WHILE" Reason: BREAK CONTINUE or ENDWHILE was found, but no WHILE was specified. Error : "ELSE|ENDIF without IF" Reason: ELSE or ENDIF was found, but no IF was specified. Error : "DEFAULT|ENDCASE|ENDSWITCH without SWITCH" Reason: DEFAULT ENDCASE or ENDSWITCH was found, but no SWITCH was specified. Error : "Must COPEN a catalog before cCOMMAND" Reason: Attempted a catalog-related command (CGETREC, etc) but no catalog was open. Use COPEN before the command. Error : "Catalog must be sorted [CSETSORT] before export" Intellicomm v2.01 SCRIPT.DOC 237 Reason: Attempted a CEXPORT on an unsorted catalog. Use CSETSORT before the CEXPORT command. Error : "Invalid sort order" Reason: Tried to CSAVESORT with no sort order defined. Use CSETSORT before calling CSAVESORT. Intellicomm v2.01 SCRIPT.DOC 238 H. SCRIPT MEMORY LIMITS To execute a script, Intellicomm first checks the filesize of the script file (as reported by the filesize you'd see in a DOS 'DIR' listing, and in the Script Manager to the right of the script filename). If less than 65530 bytes, Icom then attempts to allocate a memory buffer (the same size as the script filesize) to put the script into. If enough memory is available, the script is read into the newly allocated memory buffer all in one shot with no stripping of comments, trailing spaces, or blank lines. This is done mainly for speed, since many Icom scripts are used to enter a few characters quickly, or to enter a command from a BIF, or as a simple script for small custom jobs/logons, etc. In these cases speed counts, and wasting memory isn't an issue since the scripts are small. H.1 Developing Large Scripts If you are developing a large script that won't load into memory due to the 64K (65530 byte) limit, a fairly easy solution is to split your script up into smaller scripts and use the SCRIPT command to call the smaller scripts if/when they're needed. *Each* script is allowed 65530 bytes of memory (up to the limit of available DOS memory -- usually 640K). By using multiple scripts you can use all the DOS memory available on the computer. Here's an example of how it works: ;MAIN.SCR this is the main 'module' of your script program ; (you don't have to call it MAIN.SCR... it can be any name) ;here we call a series of other scripts to do what needs doing SCRIPT "LOGON.SCR" ;LOGON.SCR might dial and logon the BBS OFFLINE GOTO done ;if not connected, quit SCRIPT "DOWORK1.SCR" ;perform some task with another script OFFLINE GOTO done ;if not connected, quit SCRIPT "DOWORK2.SCR" ;perform another task with another script OFFLINE GOTO done ;if not connected, quit ... ;etc. done: return This is actually how many .EXE programs work as well, since there's usually no need to have ALL of the code in memory at the same time. Whatever code is needed for the current task is loaded, and when that task finishes the code is unloaded, and the memory is freed up for use by the next task (which is exactly what happens when a script ends ... the memory it was using is freed up). You need only a small control 'module' (the MAIN.SCR above) to swap other scripts in and out of memory as needed. This technique also makes your code easier to follow and maintain, since it's easier to find things in smaller scripts. If you'd like to use this technique you should first refer to the SCRTUTOR.DOC sections: "Global Variables" and "Passing Parameters to Scripts" if you haven't already. The Global Variables can be very useful Intellicomm v2.01 SCRIPT.DOC 239 for inter-script communication (telling the called script what to do). As well you might consider using the $ERRORLEVEL System Variable to return various errorcodes to your main module. You're free to ASSIGN an errorcode that would be meaningful to the main module prior to exiting the called script. For example, $ERRORLEVEL 1 might mean the carrier was lost. $ERRORLEVEL 2 might mean that a BBS event was scheduled, etc. Just use ASSIGN $ERRORLEVEL x (where x is your return code) in the called script, then use IF $ERRORLEVEL = x (where x is the errorcode) or SWITCH $ERRORLEVEL to TEST for any abort codes when the called scripts return. You should also be aware of the difference between the EXIT and RETURN command as it applies to called scripts. The EXIT command aborts ALL scripts (exits the script interpreter entirely), while RETURN simply ends the current script, returning control to the caller. So, in the example above, if something went desperately wrong in the logon you could use an EXIT command in LOGON.SCR to cancel both LOGON.SCR *and* MAIN.SCR, and return to manual mode. Alternatively the RETURN command simply exits the current script and returns control to the caller at the next line below the SCRIPT command. You can also specify 'errorcodes' after the EXIT and RETURN commands to tell Intellicomm what to do with the current automated job (if the original script was called from an automated job via a Custom Command or BIF). EXIT or RETURN followed by a positive number (1, 2, etc) tells Icom to hangup and remove the current BIF from the job queue (useful if you encounter a BBS 'event' and you have no time online, etc). EXIT or RETURN followed by a negative number (-1, -2, etc) causes Icom to abort ALL jobs, just as if the user had selected "Abort Job/Script" from the [Alt-Q] menu. There are several considerations for using errorcodes with EXIT and RETURN, and more details can be found in section ?. I. CREATING SCRIPTS FOR PUBLIC DISTRIBUTION This section is for script "gurus" or prospective gurus who have a script project in-mind that they plan to distribute to the general public. These are ONLY pointers... They are not 'rules', and you can feel free to ignore every one of them if you like. First off, some no-no's for public distribution: o Don't make the installation and setup unnecessarily complicated. It not only turns people off right at that crucial "first impression" moment, but can cause you grief if you offer technical support. o Don't use your own custom colors in your script, no matter how nice it looks on your screen. Monochrome and laptop displays cannot display all colors properly and if you hardcode in custom colors, your script may be useless to many people. Use the various $xxxx_COLOR System Variables to specify colors to display with the colors the user has set up in the Icom main setup. Better yet, use WNDOPEN, MSGOPEN, PRINT, etc., to display text on the screen, which automatically use the default Icom colors. Intellicomm v2.01 SCRIPT.DOC 240 o If you use an 'extended' (43 or 50) line video mode in the Icom main setup, make sure you set the display for standard 25 line mode and re- test your script before distribution. You may have defined menus or other screens that will not fit on other people's video displays if you used an extended line mode when developing your script. o Try to make as many things as possible configurable (see the INTRODUCTION TO FILE INPUT / OUTPUT for information on storing data on-disk), and avoid hardcoding specific drives and directories. Use the System Variables, BIF Variables, and Main Setup Variables to get the Icom data the USER has already set up where possible. Now some 'do's: o Create an @ICOM.SCR installation script and include it in your archive. Icom's POSTFILE.SCR, which automatically decompresses and virus checks new downloads, also checks for a script called @ICOM.SCR. If it's found (i.e. if you include it in your distribution archive), the user is given the option to execute it. Thus, you can LIST "README.TXT", COPY or RENAME (move) your files to install them AUTOMATICALLY, get information from the user, etc., using @ICOM.SCR. Basically anything that needs doing for installation and setup up of your product can be done automatically via @ICOM.SCR. o Test your script thoroughly before releasing it, attempting to look at it from a new user's perspective. o Document features that aren't obvious. Implement online help were possible (the LIST command will allow you to display your documentation while your script is running, which is as good as online help). o You're free to support your scripts (and take complements on your work) in any of the online forums we use for Intellicomm. Make yourself available for feedback, if possible. o If your script is has its own interface, or is otherwise "stand- alone", the best way to run it is via the DOS command line with the /scr: switch. If you include a .BAT file with your script, you can have users start it right from DOS (or Windows/DESQview or a menu system) just as they would a regular program: Echo off rem MYSCRIPT.BAT starts MYSCRIPT.SCR from DOS ICOM.EXE /scr:myscript o Pass along your feedback as to where you'd like to see improvements or changes in the script language. Implementing new script commands (particularly if you're a C programmer and you know that it's a standard library function) is usually very simple. New script concepts and rules are more complicated to code (and particularly to implement, without rendering all scripts to date useless), but all suggestions will be considered. Intellicomm v2.01 SCRIPT.DOC 241 J. CHANGES FROM THE V1.00 SCRIPT LANGUAGE Listing all the changes from the Icom v1.00 script language would be pointless, since it would duplicate most of this manual to explain them all. By reading the introductory material in SCRTUTOR.DOC, and looking at the SCRIPT COMMANDS AT A GLANCE section, you'll be able to pick up all the changes and new commands quickly. This section covers only the changes that are relevant to existing v1.00 scripts. All v1 script commands, other than those listed below, work the same with Icom v2 as they did with v1. J.1 Version 2 Syntax Changes Single quotes are no longer permitted around string constants. With the v1 script language this was legal: PRINT 'This string has "double" quotes in it.' The problem with this is that you cannot use both single AND double quotes in a string. With the addition of File I/O, where data is read from a text file (data which could contain both single and double quotes on a single line) this this is no longer practical. Thus, you must use DOUBLE quotes around string constants, and if a double quote appears in the text, use a caret to escape it: PRINT "This string has ^"double^" quotes in it." J.2 Version 2 Command Changes EXIST, NOTEXIST, OFFLINE, ONLINE, and WHEN ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These commands no longer force you to GOTO a script label. You can now use any script command after any of these commands. Examples: EXIST "somefile.ext" DELETE "somefile.ext" NOTEXIST "somefile.ext" GOTO done OFFLINE EXIT ONLINE MSGWIND "You are online" WHEN "find this" SEND "command" WHEN "find that" GOSUB handle_find_that WHEN "Begin your Download" DOWNLOAD "Z" "" The addition of the GOSUB command, combined with the ability to use GOSUB in WHENs should be quite helpful in writing your scripts. If you use a GOSUB in a WHEN, the script executes the subroutine (until a RETURN is encountered) then returns to the WAITFOR. Thus you can handle much more complex tasks with WHEN/WAITFOR than you could with the v1 script language. Further, EXIST and NOTEXIST now search for read-only files as well as normal files (but not hidden files, subdirectories, DOS system files, or the volume ID). Previously, EXIST and NOTEXIST found only files that were normal (not read-only). You can now also access all the file attributes of files found with EXIST (if the file exists) including file Intellicomm v2.01 SCRIPT.DOC 242 size, file modification date and time, and file attributes via the System Variables $FSIZE, $FDAY, $FMONTH, $FYEAR, $FHOUR, $FMIN, $FSEC, and $FRDONLY. You may also wish to replace some of your EXIST commands with the FINDFIRST command, which allows you to search for files with ANY attribute (including hidden files, subdirectories, DOS system files, and the disk volume ID). Using FINDNEXT after a call to FINDFIRST allows you to obtain all filenames in a given wildcard (*.DBF, \ICOM\BIF\*.BIF, I???.*, etc), as well as the attributes of each file. EXIT ~~~~ The EXIT command now exits the script processor entirely. Previously if you used the SCRIPT command to call another script, and the called script performed an EXIT, it would simply return to the original script. EXIT is now used to abort ALL scripts and return control to whatever called the original script (the automated job, or Script Manager, etc). To exit only from the CURRENT script (i.e. to allow the calling script to continue running), use the RETURN command. RETURN does take an optional exit code as EXIT does. Please see section ? in SCRTUTOR.DOC and the Detailed Command Summaries of EXIT and RETURN above, for more details on usage. GOTOXY ~~~~~~ A bug in the GOTOXY command was fixed for v2.0. GOTOXY 1 1 went to screen position 2, 2 with Icom v1.00. The v1 script conversion utility automatically decrements the screen coordinates in GOTOXY commands found in v1 scripts, to account for this bug fix. SCAPTURE ~~~~~~~~ This command now takes a parameter that allows you to specify a D:\PATH\FILENAME.EXT to capture to, instead of forcing the screen capture to the default Icom screen capture file. If no filename follows SCAPTURE, the usual screen capture file (\ICOM\CAP\SCREEN.CAP by default; defined on the main setup/Filenames and Paths screen) is used, as with the v1 script language. SEND/SENDNC ~~~~~~~~~~~ The SEND and SENDNC commands now observe any "Response Delay" you have set in the BIF (screen 1): | Receive Mail . . Response Delay . 10 ~~~~~~~~~~~~~~~~~~~ Since SEND is normally used in combination with a WHEN command to respond to a BBS prompt, and is also used by Script Learn mode after WAITFORs to send responses in learned scripts, a configurable response delay in the BIF can be very useful with certain BBS software. Some BBS software clears the COM input buffer after displaying prompts, and if your script had sent the response BEFORE the buffer was cleared (i.e. if the script answers BEFORE the prompt is fully displayed), it would be lost. If your SEND or SENDNC commands are not being processed by the BBS, adding a Response Delay to the BIF should remedy the situation. Intellicomm v2.01 SCRIPT.DOC 243 The equivalent commands to the v1.00 SEND and SENDNC (no delay) are SENDNP (NP for No Pause) and SENDNCP (NCP for No CR or Pause). SYSTEM ~~~~~~ The SYSTEM command now takes two parameters. Parameter 1 (a number from 0-2) tells Intellicomm what to do if connected: SYSTEM 1 hangs up, SYSTEM 2 stays connected, SYSTEM 0 (or no parameter) asks the user whether to disconnect, if connected. The second optional parameter allows you to specify an ERRORLEVEL when exiting, which can be tested from a .BAT file or similar. If you use SYSTEM 0 1, then errorlevel 1 is returned to DOS and could be tested: rem A .BAT to run your script from the command line ICOM.EXE /scr:myscript if errorlevel 2 <do this> if errorlevel 1 <do this> ...where <do this> was a valid batch command (GOTO, DELETE, etc). WHEN ~~~~ Aside from the previously mentioned change to WHEN, you can now also track up to nineteen BBS prompts using WHENs instead of seventeen, the v1.00 limit. J.3 Icom v1.00 Script Conversion Version 1 scripts are optionally converted when you install Intellicomm. Aside from making sure that there are DOUBLE QUOTES around all strings (necessary now that variables have been introduced), all the conversion does is to place GOTOs in the ONLINE, OFFLINE, etc., commands listed above, which no longer force a GOTO. The more subtle changes with EXIT and CAPTURE are not checked, as they would be difficult to convert automatically. You should give your converted scripts a once-over just to make sure they're doing what you want. If you converted your scripts during Icom v2 installation and want your original v1 scripts back for some reason, you'll find them renamed to *.OLD in the \ICOM\SCR directory.